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VIEWPOIlUT 


By Nick DeMello 



PuYs Weix wrm Ottors 

My mother told me that the secret to getting ahead in Itfe is being 
flexible and Ictiming how to gel along well with otliers. Frankly, you can 
often loose more by insisting on having things your w^y, tlian you gain 
by doing sr^mething the ""right" way 1 tliink Apple has taken this wisdom 
lo hean last year and lias Iciimed to pick ilieir fighis very caietully. 
Today"s i\iac definitely plays lietier widi otiiers, and tliat may just translate 
into a larger market sliare in die coming year. 

The Mat intosh is a wonderful and unique instrument that offers 
so many powedVd features and is so easy to use and fun to explore 
that one has to wonder why everyeme doesn't have one on their desk. 
Well, the reason often comes down to compatibility. Macs are great, 
but replacing my hard drive costs twice as muc h as it should, it can 
be easier to find an lionest politician than a really great joystick, and 
you can't get gcxid games for it For love or money, Well at least that 
used to be true. It simply didn’t make gocxl business .sense for third 
f>anics to address Lliosc markcLs, 

Apjile’s adoption of IDF hard drive.s may have Ix^en tlie first sign. 
Buying a Macintosh computer suddenly liecame a lot more cost efteaive 
(by hundrexis of dollans on ihe hard drive alone) and Mac users now 
have access to expansion OfXitnis tliat simply wcTen’t available Ixfore — 
at any price. I Mill ieux:nil>er turning ovei' every stone I could to tiy and 
find a 800 mb SCSI liard disk for my Duo, when my bucldy with the 
TliinkPad could pick up a 2 gb IDR HD at the comer computer store — 
chc^aixT. Adopting IDE has made tlie Mac a itiorc^ useful t<x)i for many 
of us and therefoR" an easier choice for fuH time buyers. Adopting USB 
was an even tener move. 

Over the ycitrs, many vendors liave made wonderful fX!riphe!-als 
for tile Madntoslv but let’s not kid ourselves. You could walk into any 
computer .store and see aisles of joysticks, ke^^xiards, specialty mice, 
and Ollier inptii tievic'es. It was always a lot of fun exploring thest; 
aisles... Lintil you realized dial tlie Mac section was over tliere (that 
tx>ttom sShelf w ith two mice and one Joystick). For mcxsl vendors, it just 
didn I pay lo build an enlirc^ly separate piece of hardware for the Mac, 
tile market was kx) .small. Bui lliai lack of choke also kepi the market 
IVtim growing, creating a vicious cycle tliat Apple has tried very hard to 
fight again.st for over a clecRle. 

Well, it seems Apple has given up. Or, more accurately, realized 
that there are Mime Ixiiiles that it is stiti[>ly foolfsh to fight — esfx:cially 
w'hen rho,se same resources can lx*tter be applied elsewJiere. \X1iy not 
tap into tlie huge Rservoir of peripheral vendors tliat happen to be 
making Uxils for itie FC and make ii easy and profitable ft>r them to 
sell to the Apjile market as well? Witli the eineigence of the USB 
standard it was perfed time to do so, and now^ I can get a great 
Joystick for my iMac. Ifs no longer a hard sell to convince a vendor 
to support the Macintosh, in.slead ifs a no brainer for them to increase 
their market share by si mply cr eating a Mac OS driver fo r tlie exac t 
.same hardware they’re already selling to FC aistomers. It now makes 
good bn.sfnes.s sense to support the Macintosh. 


Tlien there's OpenGL If you’re not familiar with OpenGL, thafs not 
too surprising. It liasn’t Ixen voy |x>puiar witli Mac piogramnias over 
tlie years — it’s just the rest of the computer world that’s laeen relying on 
It. OpenGL is a grapliics library that, since 1992, has been tlie de facto 
standard ftjr 5D Graphics programming. Tfie OpenGL engine suppoms 
the easy and platform independent generation ;md manipulation of 
detailed 3D coasmias as well as advant'ed rendering optioas like 
reflections, refraction, and transparency. Thi.s hill niy tracing engine has 
been incorporatesJ into mast mcxlem opCTating systems. Because you 
could count on OpenGL lieing available in every inMallation of Windows 
98, you only had to wmte a fraction of the code that you needed to to 
create the same gajTte for the Mac. At Macworld San Franc:isc:o, Apple has 
finally announced that OpenGL will tie implemented in die next lelease 
of the Mac OS 8.x and will lie integmted into Mac OS X as well 

So what does this mean to game programmers? It means 
exactly w'hai USB meant to f>eriphcTal manufacturers: all those 
wonderful 3D games out there, the ones based on OpenGL game 
engines can now he poned to the Mac with very little work. It 
means that the Mac can take the best that Winckiw.s has to offer and 
make it trur owm with very little effon. 

While many Mac’world attendees w^eie ofT tcxcstirig OpenGl, those 
who wc^rn't prograiTuners were fcKaised on (tnother annuuncemcni. 
Conne<tix, those wonderful Folks who linmghl us Viitiial PC, announced 
tile Vinual Game Siaiion — a Sony PlayStation emulator for the Mac. 
After all, if the Mticintosh is going after computer gamers just trying to 
match the Window's offering Isn't m:tlly setting much of a diallenge for 
ourselves. Sony is the king of play lime. 

Witli Ap[>[e promotions tliat bundle Yirtual l^C witli new Macs and 
Cormectix .scaling tlie Virtual Game Smtion at an extremely attraaive 
pria^, tlie Mat inrash is now the only .system cm wliich you tan play jusi 
a!x)ut any game made. Tliere may lx: a new' king in town. 

Steve Jolis dEx^.snf need any back patting from me. He’s a slirewd 
lxi.sine.ssnian who understands tlie computer market better than 1 ever 
will. Never die less, I want U) lip my hat hem. Apple has CTeuIcxl a new 
line of a>niputers that offer tremendous specif ixiwerful graphics, easy 
expandability', and an increasingly .stable and reliable feature rich 
operating system. But I think we may jnst come to see lhat ihe teal 
strokes of genins in die resurgence of the Maeinltjsh lie in die quieter 
moves Apple has made to set tlie surge for a growth in market share. 
Ikyond amdy coloiied boxes and monsijoiisly powerful CPU’s, Apple’s 
subiler ticrisions witli mgaid lo siandards and emulation alkiw tlie 
pladbrm to effortlessly Ul[) into die treniendous tliird party hardware 
support of the Intel PC, the army of game progninimers relying on 
OpenGL, and the we^alth of existing games on Windows anti PlayStation 
platforms. This just nuiy mean the difference lieiween a neinvigorated 
Mac platform reclaiming our comfortable niche in tlie computer indiistiy. 
or expanding to Lieconie .sometliing larger, 
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STARTED 


By Dan Parks Sydow 


Asynchronous Sound: Action and Sound 


How a Mac program plays sounds that 
coincide with animated effects 

In ksi month's Getting Started we covered sound-playing 
basics, llie infonmtion in that article provided a good framework 
for including sound in your Mac applications. However, one key 
use of sound wa.s omttied firom that article — the playing of sounds 
asynchronously. Asynchronous sound playing is the playing of a 
sound in such a way that odier action can take place for the 
duration of the sound. Rather than liave your program — and the 
user — wail while a sound plays, youll want other events to take 
place. Most typically asyncbonous sound playing coincides with 
animation. As some animated effect goes on in a window, an 
accompanying sound plays, 'FhLs month we'll tackle asynchronous 
sound playing so that you can turn your programming efforts into 
a reaJly polished multimedia Mac application. 

Sound Channels 

when a program is to play scjund data that's loaded into 
memory, the program must create a corresponding st)und 
channel that holds a queue of sound-playing commands for that 
data. A program that calls SndPlayO and passes a nil pointer as the 
first parameter is telling the Sound Manager to take care of the 
alkx:ation of the sound channel. ITiat's exactly what we did in last 
month's Getting Started column for the SoundPlayer program: 

SndPlay{ nil, (SndListHandleHheHandle. false ): 

If your program plays a sound synchronously, as SoundPlayer 
did, then letting the Sound Manager take care of the task of creating 
the sound channel makes sense. No action otn take plac:e in a 
program during synchronous sound playing, so tlieie's no need lo 
access the sound channel If your program is to ir^tead play a 
sound asynchionoasly, then your program mil want to keep tabs 
on the sound channel In particular, your program will want to 
iasert a special command into the sound channel after it starts 
playing a sound This command will be used by the sound channel 
to notify your program when sound playing ends. As long as the 
sound is still pbying your program knowsJtjcan cany on with 
some other action — typically another step, or frame, in an 
animated sequence that is choreographed with the sound. 


To allocate a sound channel, use the Toolbox function 
SndNewChannel(). A call to this function creates a new sound 
channel record and returns to your program a pointer to that record: 

SndChamielPtr tLeCbamiel i 

SndKewGhannei( StheChanBel, 0» 0, nil )i 

The first parameter to SndNewChannel() Ls a pointer to a 
SndChannefPtr. When the routine completes, the Toolbox will have 
filled in thLs first parameter with a pointer to a new sound channel 
record. Tl^rc second parameter is a ainstant that indicates the type of 
sound data that is to be played on the new channel. Passing a value 
of 0 means the channel can l>e used for any type of sound. The tliird 
prameter can be used to supply channel initialization information. 
Again, simply psiss a value of 0 if you're uncenain of the exact type 
of sound that is to be played from the channel. For synchronous 
sound playing, the last parameter can be nil. For asynchronous sound 
playing, the last parameter is a pointer to a callback routine. As you'll 
see ahead, a callback routine Ls an applicution-defined function that 
the system executes when a sound has finished playing on this 
channel. It’s impt>rtant to take note of that last point: even though 
you'll write the cxxle for the callback routine and include it in your 
source code listing with your other applicaiionHlefmed louiines, it 
will be the Sound Manager that invokes function, 

Sound Comjwands 

When you participate in the allocation of your program's own 
sound channel (rather than allowing the Sound Manager to do all 
the work), you gain the power to send sound commands of your 
choice to the sound channel. A sound channel includes a queue of 
sound commands. Each sound command can affea the way in 
which a sound is played. Each sound command has a type and one 
or two command oplitms. Consider the amplitude sound 
command, which affects the amplitude (volume) of a sound. For 
this command the type is ampCmd, the first option holds the 
amplitude (a short value in the range of 0 to 255), and the second 
option is ignored. To define a sound command that can be used to 
set the amplitude of a sound to its maxiitium, use this code: 

StidCOffiflssn'fr tteCctaffiSftd; ^ 

theCommand. cmd = aiiipCmd : 
theCoiunand. pa r a m i “ 255; 
theComfiiand. pai:aia2 “ 0; 
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The alx>ve code sets up a sound command, but it doesn’t afFea 
any partiailar sound cl^nnel. 'lb place the command in an existing 
sound channel, call the Toolbox hinclion SndDoCommandO: 

SndDoCoramandt tbeChannel. fictheCoraiHand. false ): 

The first parameter to SndDoCommand() is a sound channel 
pointer. In the above call the sc^und channel pointer theChannel 
is die one created earlier in diis article with the call to 
SndNewChannel(). Ihe second parameter is a pointer to a 
command. Before calling SndDoCommand() yooil want to have 
created and filled in Uiis command, as shown for the ampCmd in 
the previous snippet. The last parameter tells the Sound Manager 
what to do if the specified sound channel’s command queue is 
full, A value of true means an error is to lx.' relumed, wliile a 
value of false means the Sound Manager is to wait for a free 
position in the queue. 

A call to SndDoCommandO places a command in a stiund 
charmers command queue. Once a sound is played on dial sound 
channel, tlie command goes into effect. For instance, if the above 
ampCmd was placed in theChannel, then any subsequent sounds 
played on lliaL channel would lx: played at full volume. 

Asynchronous Sound and the Callback Routine 

So far we’ve diseuxssed the sound channel and the sound 
corninands tlral can !x placed in die channel — but we haven’t 
seen how those topics tie in with asynchronous sound playing. 
We’re just about there, Before getting into the details of 
implementing asynchron(>us sound, leils step liack to get an 
overview of die sound channel, sound commands, asynchronous 
sound, and something referred to as a callliack routine. 

To play a sound resource asynchronously, you’ll first 
allocate a new sound channel using SndNewChannel(). In the 
call to SndNewChannelO you’ll specify the name of a caliback 
routine. ITiis callback routine is a function that is to execaite 
when this newly created sound clianncl finishes [ilaying a 
sound. Next, you1l load the sound to memory and call 
SndPlayO to play it. After the sound begins playing, you’ll ciill 
SndDoConrimandO to add a callback command to the command 
queue of the sound channel that's playing the sound. The 
timing of the addition of this command is important. Because 
the sound has started playing, the newly added callback 
command will be placed at the end of the sound channeFs 
command queue. Doing this means that the sound channel 
executes this command when the sound has completed. 

A callback routine is a simple function that exists to tell 
your program that a sound has completed playing. When 
your program gets this information it knows that any action 
taking place that was to be timed to the playing of the .sound 
should now .stop. 

Before looking at the code that makes all this 
asynchronous business possible, let’s complete the overview 
with a list of step.s necessary to make sound and animation 
happen together: 


L Create a sound channel, pairing it with a callback routine. 

2. Begin sound playing on the new .sound channel. 

3 . Add a callback command to the sound channel that is 
playing the sound. 

4. Enter a loop^ with each pass through the loop performing 
a step in an animaiion. 

The above steps seem straightforward enough, bur the last 
step may puzzle you a bit. Performing animation using a 
loop is simple enougli — you can just move a picture a pixel 
or two at each pass through the loop. But as the loop 
execytes, how does the loop know when the corresponding 
sound has ended, and dial animation should cease? That’s 
the job of the callback routine and the system. When the 
sound ends, the system executes the callback routine — 
even if your application Ls in the middle of an animation 
loop. Your callljack routine will be written .such that it sets a 
global flag indicating that sound playing has ended, it will be 
this flag that the animation loop looks at and relies on in 
order to know whether to continue or to stop animation. 

Asynch Player 

This month's program is called AsynchPlayer. If you read 
Jast month’s column, then much of the code will look familiar 
to you — though as yoirll see ahead we'll be adding a few 
twists. Running AsynchPlayer results in the appearance of a 
menu bar and a window. Of significance in the menu bar is 
the Sound menu. This menu has a single item — Play and 
Move, Choosing this item causes the program to play a sound 
and move a picture. The sound is die disiinctivc noise of a 
helicopter flying, and the picture is chat of a helicopter. When 
the Play and Move item is selected the helicopter appears and 
moves from right to left as the sound plays. When the sound 
stops, so does the animation. Figure 1 .shows the helicopter 
as it crosses the window. After running the animation a few 
times, choose Quit from the File menu to end the program 
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Creating the AsynchFlayoi Resources 
SvAn liy opening your CocleWtirrior development fokler and 
erouing a folder named AsynchPlayer. l^un<.:h Re.sEclit and create 
a new resource file named AsynchPlayecrsrc inside die 
AsynchPlayer folder. Figure 2 shows the seven types of 
resources used by AsynchPlayer ff youVe been keeping op with 
Getting Sk4r(ed aiticles, each tyjx^ should be familiar to you. 



AsyncliPlayer includes a single snd resource — as shown in 
Figure 2. Tliis sound restiiirce is a digitiv'ed sound obtained from 
an external source — it can’t lie cxeated from within ResFdit. This 
month's piioject is available for download front MacTcch's ftp site 
at <ftp://ftp.mactech.cam/srd>, and it includes a single system sound file 
named Helicopter. Use ResFdit to open that file^ cf>py its one snd 
resource, and then iraste that resource into the AsynchPlayer.rsrc 
file. Front last month's coUimn you know tliat ResEdit won't 
display anything useful about a sound resource (since it’s difficult 
to graphically display a sound), so there's no need to double-click 
on the snd resource to peek at wfiat's inside. 

AsynchPlayer needs one picture resouree in order to carry 
otii I lie animal ion. If you're arfisriadly inclined, or if you have a 
large clip art collection, you'll be able to come up with a 
helicopter picture. Otherwise use the HelicopterPICT file 
inciudeci in project that can Ix" downloaded from MadlecIVs ftp 
site at <flp://fEp.mactech.com/src/>. In any case, get the piaure to the 
eliplxiard and paste it into the resource file- As sht>wn in Figure 
3, I lie re.sulting PICT resource should have an ID of 128, 


The tine WIND restmrec is used to create the wintlow tfiat 
displays the moving helicopter. This window won't Ix! movable, 
so you don't have to be too selective about what type of window 
you crcitle. Tlie piT>gram won't care where the window gets 
positioned on the screen, but it will be expecting liie window tti 
be about pixels in width and 150 pixels in height — so do 
use those values. Make sure the WIND has an 10 of 128. 

Tlie one ALRT and one DITL resource used by AsynchPlayer 
are the same ones used in tlie last several Getting Started 
examples. These resouretts are used in the display of an error¬ 
handling alert displayed by the program’s DoError() routine. 

Figure 4 shows tlie four MENU resources the AsynchPlayer 
program uses. After creating the MENU resources, create a single 
MBAR res<)urce that includes the ID of each of the four menus. 


I MENUS from RsynchPloyerrsn: ^ 




o 


RbDut RsynchPla^l 

Quit 38Q 1 


1 


128 


1 Undo 

siz 

Cut 


Copy 

SIC 

Paste 

§gH 

Clear 



f3G 


128 


Sound 


Ploy end Moue | | 


131 


4 -. 


figure 4. ^fbe AsyncbPia}H.r menu resources. 




PlCTs from BsynctirPleiier.rsrt. 


OlPiani^l2Bfnim 


123 


Figure JL The picture resource used in animation. 


That completes the AsynchPlayer.rsrc file. Now save the file and 
quit ResEdit — weTe ready to write some code. 

Crfating the AsynchPiayer Project 

Create a new project by launching CodeWirrior and then 
choosing New Project frcini die File menu. Ba,sc the file on tlie 
MacOS:C_C++:MacOSToolbox:MacOS Toolbox Multi-Target staEonary. 
Unchec:k Ihe Create Folder check box before clicldng the OK 
button. Give the project a name of AsynchPlayer.mep, and make 
.sure the AsynchPlayer folder is set as tlic projeefs desEnaiion. 

Next, add the AsynchPlayer.rsrc file to the project window 
and remewe the Silly Balls, rsrc file. Since the AsynchPlayer project 
_doesn't use of any o f the standard ANSI libraries, go_ahead and 
remove the ANSI Libraries folder if you feel so inclined. 
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Next come rhe program's fiinction prototypes. 


Now <:hcx)se New from the File menu to create a new, empty 
source code window. Save it with the name AsynchPlayer.c. 
Choose Add Window from the Project menu to add this empty file 
to the project. Itemove the SiltyBaJIs.c placeholder file from the 
project window. Now get ready to type some source code. Or, 
save some work and download t!ic entire AsyncliPlayer pn>jeti 
from MacTech's ftp site at <ftp://ftp.mactech.ct)ni/src/>. 

Walking Tiikoligh the Source Code 

Now, in its entirety — the AsynchPlaycT code. AsynchPlayer 
l)egins with the usual parade of constant defmitions. Many of the 
constants define resource IDs, including ksnd_ReslD for the 
sound resource and kPICTResID for the picture. 

.."/ 


ffdeflne kWlMDResID 

120 

^dfiflne kMflARBcaU) 

126 

jdcflno kALRTReslU 

128 

ifdefitie ksnd.„KeElD 

12000 

jUdEfinE kPICTReBiD 

128 

Idefine kSleep 

7 

jdefine kMoveToFront 

(WindowPLrJ It 

Ifdefine inApplc 

128 

tfderine iAbiut 

1 

l^define mFile 

129 

^define iQuit 

1 

^define mSound 

131 

^define IMovePlay 

1 


A.synchPlayer needs several global varial>les, including tlie 
always-[iresenl gDone flag that tells the program that the user has 
elected to quit. The Boolean variaiilc gCallbackExecuted tells the 
program whether a call to SndPlayO has just completed (true), or 
is slill executing (false). 'Ilie variable gSoundChannel is a sound 
channel jxjinler lliai well use to associate a caUback iouline 
with the execution of a call to SndPlay(). Variable gSoundHandle 
serves as a reference to the sound resource data dial gels loaded 
to memory. Tfie PicHandle variable gHelicopterPicture serves as a 
reference to the picture resource data that gets loaded to 
memory. Variable gPictRect is the Ixmnding rectangle of the 
helicopter picture. The last four variables (gPictStartX. 
gPictStartY, gPIctWidth, and gPictHnight) define the .starting 
coordinates for the helicopter ixclure, Rac:h time ihe u.ser 
chooses Play and Move from the Sound menu, the picture begins 
its animation at these ccxirdtnates. 


global vtjriiihk^ * 


Boolean 

Boolean 

SndChannelPtr 

Handle 

PicHandle 

Ref’t 

shori 

uhort 

short 

short 


gDone; 

gCalibaekExecuted ” fal.se: 
gSoundChantiel; 
gSoundHandle “ nil; 
gHel!Copterpictare; 
gPicUtect; 
gPictStartX = 500; 
gPictStartY = 35; 
gPlcrWidth - 2S6; 
gPictHelghr = 82: 


ftmedons *******************^/ 


void 

ToolBoxJnlt t void J: 

void 

MenuBarInitC void ); 

void 

InitWindowt void 3: 

pascal void 

SndChannelCallhackC SndChanaelFtr* Sndtkmmiand) 

void 

PlaySoundResourcef void ): 

void 

AniBiateWbileSoundPlays( void ); 

void 

EventLodpt void ); 

void 

lkiEvent( EventRecord ‘eventPtr ); 

void 

HandleHoueeDownt EventRecord *eventPtr ): 

void 

HandleMenuChoiceC long menuCholce ): 

void 

HandleAppleChoice( short itom ); 

void 

HandleFiieChoiceC short item ); 

void 

HandleSoundCholeet short itera }r 

void 

DoErrort Str255 errorString 3; 


The main() function begins by initializing the Toolbox. Just 
as we did last month, a check is then made to ensure that the 
user has version 3-0 or later of the Sound Manager. That version 
of the Sound Manager holds a lot of sound-related goodies your 
program may want to take advantage of, so if the user doesn’t 
fctve 3.0 or later, die applic'ation-defineti routine DoEnror() posts 
a message and exits the program. 

void taalnC void ) 

I 

NuraVerslon theSndMftrVers: 

long cheREsponse ; 

ToolBoxInitO : 

theSndKgrVers SridSoundManugerVenaionO ; 

If { theSndHgrVers.majorR ev < 3 ) 

Lk>Error{ “\pBound Manager ie outdated*’ ): 


Before c^irrying on with tile msi tjf die iniiializadons, main() 
makes a c:dl to the Tcxiibox function Gestalt() to see if die asefs 
umciiine is exjuippe-d with a PowerlK] processor. While it's possible 
to achieve asynchronous sound on a 68Kdia.sed .Mac, the details of 
achieving tluit feat are out of the scope of this article. Apple no 
longer produces 6SK-based Macs, owners of (>lder Macs are 
upgrading to Power Macs, and a grc'at tlirai of new^ Mac softw'are 
relies on very fast processing power. Witli that in mind, expert to 
see support for 68K-h;ised Macs waning in tlie futuie. If you need 
to sujiport 68Kdiased machines lor your own a.5ynchiDnous 
sound-playing application. lead up on the topic of I tie A3 World, 
and dig into the Scmrid volume of 

Gestalt ( gestaitSys Architect are, IrtheResponse ]; 

if ( theResponse !“ gestaltPovetPC ) 

DoErrorf ’‘\pThiB program only runs on Powder Macs*’ ); 

MfinuBarTnit £): 

InitWindowO r 

EventCoopO; 

I 
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The ToolBoxfnitO and MenuBarlnit() functions are tlie same as 
prior versions. 

void ToolBoxInit( void ) 

( 

IoitGr af( qd,t heFort ): 

InltFonts{); 

InltWindavs (); 

TnltKeniis (); 

TFInlLO ; 

InitDialogs( nil ); 

InitCursjor (): 

I 

ML-nuJ3arJnit 

void MonuBarTnirt void ) 

I 

Handle luenuBan 

HetiuHandle menu; 

roenuBar ^ GetNa¥MBar( kMBAEResID }; 

SetMeniiBar( aemlBar ); 

Eaenu ^ GeLHonyHnnd1o( mApple ): 

AppentlReiil1enu( menu, *DRVR' J; 

DrauMennBairO : 

J 


InitWindowO creates a new window from the one WIND 
resource, then calls ShowWindow() to show the window and 
SetPort() to ensure thai drawing takes place to this window. After 
tliat the PICT resource is loaded into memory and the returned 
picture handle is stored in the global variable gHelicopterPicture 
for later use during animation. 

void InitWlTidowi void ) 

I 

Wind ovPt r wi ndo w; 

window - GotNfiwWlndowC kUINDResID, nil, (Windowptr)'IL ); 
StiowWlndowt window ); 

SetFortC window ); 

gHelicopterPicture ^ GetFictute( kPlCl'ReslD J: 
if ( gHelicopterPicture nil } 

DoError( “\pAttempt to load picture resource failed" ); 


Next we write the callback routine that's to be used by a 
call to SndPlayO^ The format of the callback routine is: the 
pascal keyword, a return type of void, the function name, and 
a SndChannelPtr parameter and a SndCommand parameter. 
The l)ody of llie callback routine can include any code you 
want, but it typically just toggles the value a global variable 
from false to true. Thafs what we do here with the Boolean 
variable gCallbackExecuted. 


pascal void SndCljunrielCanBacli ( 

i 

gCallbackExecuted “ true: 

J 


SndChannelPtr theChaunel, 
SridComiiand theComiDand ) 


If gCallbackExecuted is set to false at some point before 
sound playing starts, tlicn the program will know sound is 
playing and will animate — and continue to animate — until it 


sees that gCallbackExecuted lakes on the value true. Tliat 
happens when tlic sound ends and the system automatically 
invokes our SndChannelCallback() callback routine. 

Now, the meat of the program — PlaySoundResoufce{). In last 
month's version of this sound resource playing routine, the 
following occurred: a sound resource was loaded, the resulting 
handle was locked, SndPlayO played the sound, the handle was 
unlocked, and the handle was released from memory. All of these 
adtons again take place lliis month, liut because the sound is now 
l>cing played asynchronously we need to add a few more steps. 

PlaySoundResourceO begins with a call to die Tooll)ox 
routine NewSndCalfBackProc{). This function creates a universal 
procedure pointer (UPP) to a caOback function. In short, we Ve 
just created a pointer to our own application-defined function 
named SndChanne!Callback(). This UPP will l>c used just ahead. 

pUySouiidRcscKinrc ««*«*•*«•« 7 

void PlaySoundResourcef void 1 
1 

OSErr theErr; 

SndCallBackUPP callBscktIPP: 

SndCoimnund thoCoiiima;id; 

callBaDkUFP = N^vSodCallBackFrocC SridCbaiinc!! Call back ]: 

Next, a call to SndNewChannel{) is made to create a new 
sound channel- When a sound channel is to lye used to play 
asynchronous sound, a universal procedure pointer to a callback 
routine should be the last parameter. We've just created that LIPP, 
so we’re all set: 

theErx * SndNewChanneK ^gSoundChannel, 0, 0* 
callBackUPP ); 

if t IbcErr noXrr ) 

DoEtEort “\pNew sound channel failed’’ ); 

Now tlie data from die sound resource is loaded to memory. 
Well save the resulting handle in the global variable 
gSoundHandle: 

gSoundHandlo = GetResourcet 'snd ksnd_RcsTD ): 

if { aSoundHandle nil ) 

DoErrort “\pAttempt to load sound resource failed” ): 

When a sound is playing asynchronously, just about any 
action can take place. Our very short Asynch Player example 
program doesn’t do anything Uk) Lrieky, so we can be reasonably 
sure nothing l>ad tnight take place during sound play. But a 
larger program could include code that closes an open resource 
file. If that file is the one that holds the stiund resource that’s 
being played, things could gel ugly. So when playing a sound 
asynchronously it's wise to take the precaution of detaching the 
sound resomce from its resource file. Even though die sound 
resource data has been loaded to memory, lliem could still be a 
dependency on information in the resource itself, Detaching the 
resource removes any dependency' on the resource file. 

DetachResourcef gSoundHandle ): 
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Next, lock ihc sound handle — jusi as was done in last 
month's example- lliat prevents the sound data from getting 
moved about in memory as die sound plays. 

llLockl gSoundlilandle ) : 

Now set about playing the sound by calling SndPlay(), Here 
weVe using SndPlay() for asynchronous sotind playing so we 
need to provide our own sound channel ptwinter as the first 
parameter, a handle to the sound to play as the second 
parameter, and a value of true (for yes^ we’re playing 
asynclii'onous sound”) for the last parameter 

thefirr = gSoundCbatinel, 

(SndListHardle)gSoundHandle, true ]: 

if ( theErr \= noErr ) 

DoErrori “\pFlayiTig of sound failed" ): 

Now, with .sound playing started, we need to slip a sound 
command into tlie command (lueuc of the sound channel that’s 
just begun playing the sound* Earlier in this article you saw how 
to do that' define the fields of a SndCommand variable and caM 
SndDoCommandO to place the eommand in a sound channel’s 
queue. Here we define tlie siiLind command to Ijc of tire type 
callBackCmd. For this type of command botii options (the paraml 
and param2 fields) are unused. 'I lie call to SndDoCommandO placxfs 
theCommand in the sound channel pointed to by gSoundChannel 
'Ihe third parameter value of false tells tlie Sound Manager to wait 
for an opening in the sound channel’s queue if it is ciuTently full 
(wiili rtx)m for 128 cT)mniands, an unlikely event). 

LlieCoiMiarid. emd '=*^ callBackCmd: 

theConunurtd.paraml = 0: 

theCojiraiand,paramZ * Os 

theErr = SndDoConimand (gSoiindChaniiGl, SthcConimand , false): 

If ( theErr noRrr ) 

DoError( “\pSuund conmaiid failed” ): 

Now diat sound has .started, it’s also time to sian the 
animation. We handle that in a separate application-defined 
function named AnimateWhiioSoundPlaysO. A call to that function 
ends the PlaySoundResource() code. 

AnlirateWh i leSoiindPlay s {): 

When sound starts, so dex’s animation. For our simple 
example all wg need to do to achieve an animated effect is to 
offset the picture boundary rectangle by one pixel in the 
horizontal direction, A call to OffsetRect() dex^s just that. At each 
pass through the infinite while l(K>p, gPlctRect is repostUoned one 
pixel to the left. Ihis assumes, of course, that the sound is still 
playing. Well know this to be the case if gCallbackExecuted 
remains false (the value the variable was initialized to when it 
was declared), As long as this flag is false (and note that its value 
IS checked at each pass through the loop), animation continues. 


void AjiimateWhileSoundFlays { void ) 

I 

OSErr theErr: 

wtiile ( true ) 

I 

if ( ^CallbackExccuied = false ) 
f 

OffsetKectf &gPictRect, -1. 0 ): 

DrawPicture( gJielicopterPicture» 

I 

Once sound playing has a)mpleted, the system invokes the 
callback routine. Tliat function sets gCallbackExecuted to true, 
which gets picked up on by the loop in AnimateWhileSoundPiays(}. 
With Lite callback routine executed, it’s time to wrap things up and 
end tlie rmimation kxjp. A call to HUnlock() unlocks the memory 
that holds the sound data, and a call to ReleaseResourceO frees up 
tliis memory. We then dispose of the st)uncl channel — a 
necessary step because we were the ones who allocated it. The 
global variable gSoundChannel is set to nil since it no longer points 
to valid data. ’Hie global flag gCallbackExecuted is set to false in 
preparation for the next call to SndPlay{) (an aa which occurs if' 
the user again clicx>ses Play and Move from ihc Sound menu). 
Finally, return breaks the otherwise infinite while loop and ends 
the AnimateWhifeSoundPlaysO function. 

else 

I 

HOnlockt ftSoundHandle ): 

ReleaseResDurce( gSoundHandle ): 

gSoundHatidle = nil; 

theErr = SndOisposeChannel( gSoundChannel. true ); 

if ( theErr !» noErr ) 

DoError( "\pDisposing of sound channel failed" ): 

gSoundChannel * nil: 

gCallbackExecuted false: 

return : 
t 


Tliat jusi alxjut d{)e.s it for tlie new stuff. The remaining 
AsynchFlayer code is the basic stuff found in just about every 
Mac program. The only new code is a couple of minor additions 
to the code that liandle.s a .seletiion from the Sound menu. 

PvCJlTUHjp -********^^*»*/ 

void EventLoopt void ) 
i 

Ev&ntEecord event ; 

gDonc = false: 

while ( gDone ^ false ) 

f 

if ( WaltNej£tEvent{ everyEvent, Sevent. kSIeep. nil ) ) 
DoEvent{ Stevent ): 

1 


void BoEveat( EventRecord *eventFtr ) 
f 

chaftheChar; 

switch ( BventFtE >wliat ) 
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c!a^B notiseDowti; 

HandleMouseEkjwnC eventPtr ): 
break; 

case XeyDown: 
case autoKey: 

tbeChar " eventPtr >incssage (r charCodeMask: 
if { (eventPtr >siodifiers & cmdKey) 1= 0 ) 
ilaiidleMenuChoiceC MenuKey C theChar ) ) : 
break; 

case updateEvt; 

Be&inUpdateC CWindowPtr) (eventPtr->iBfisaage) ): 
EndUpdate( (tfindowPtr) (eventPtr->iiiessage) ); 
break; 

I 

} 


r*-^***"*-’’ ilaiKikMouscDuwn 

void HandleMouaeDownf EventRecord ‘eventPtr ) 

i 

WlndowPtrwindow; 
short thePart; 

long menuChoice; 

thePart - FindWin£iow( eventPtr->where, ^window ) : 

switch ( thePsrt ) 

I 

case InMenuBan 

menuChoice “ MenuSeiectC eventPtr->where ): 

HandleMenuChoiceC menuChoice ); 

break; 

case inSysWindnw : 

SynteoiCHckC eventPtr» window ); 
break; 

I 

1 


Here in HandleMenuChoice{) weVe added a switch case 
section for the handling of a selection from the Sound menu. 

Z™™”" llaadJcMtutiaioice 

void t?andlelfenuCholce( long tncnuChdicc ) 

I 

short nenu; 
short iteu: 

if C menuChoice 0 ) 

E 

menu = HiWordC mencCholce ); 
item “ Lo¥crd( mcnuChoice ): 

switch { menu } 

\ 

case mApple: 

HandleAppleChoice( Item ): 
break; 
case mFile: 

HandleFileChoicet item ); 
break: 

case MSound: 

HandleSoimdChoiceC item ); 
break: 

I 

HiltteHenid D ): 
i 
I 


‘ IlandJeAppkfChoice ‘ 


void flandleAppleChoicet abort ticm ) 

I 

Men LiTfa (idle apploMtuia: 

Slr2Si> accName: 

short aecNiimber; 




ftSJerti 


f/iP— 

f S«p*r 

P*s<fTo; 


^Mess^ 


f^eclpients 
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svitch ( item ) 

I 

case lAbout: 

SysBeepC 10 ): 
breaki 
defaults 

appleMenu " Getf1enuHandle( nuApple )i 
GetHeDuItemText( appleHenu, iteni» accMame )j 
accNumber = OpenDeskAcc ( accKame ); 
break; 

I 

I 

/•“".. HamlleFlleOiok<? 

void ilandlsFileCholce( short Itenn ) 

[ 

switch ( item ) 

! 

case iOuit: 
gDone " true; 
break: 

[ 

1 

When the user chooses Play and Move from the Sound menu, 
HandteSounolChojceO gets invoked Before calling 
PlaySoundResourceO to start the sound and animation, the global 
rectangle that holds the starting boundaries of the picture ts 
reset. 'Ihis places the picture at the far right of the window so it 
can begin its journey to the left side of die window. 

iiwidkSouiidaioicc ***«*“‘*™7 

void HandloSoundCholcet short Item ) 

I 

switch C item ) 

I 

caso iMovePlay: 

SetRect( ^gPictRect, gPictStartX* gPictStariy, 
gPictStartX + gPictWidth, 
gPictStartY + gPictHcight ): 

PlaySoundResourceO ; 
break; 

1 

J 

void DoError( Str255 errorString ) 
t 

ParamTextC errorStriug. "Vp*** "\p" ): 

StopAlertC kALRTResIDp nil ); 

RxltToShellO; 


Running AsynchPiayfr 

Rim AsynchPiaycr by .selecting Run from tJie Project menu. 
After tlic code compiles, a menu bar and an empry window 
appear Choose Play and Move from the Sound menu to confirm 
that the sound that plays coincides with the animation iliat takes 
place. Depending on tfie speed of your Mac, the helicopter may 
or may not make it off the left edge of the window. If the 
helicopter does exit the window while the sound is still playing, 
you may want to make the window larger (and move the starting 
point of the picture farther to the light) so that you can verify 
—that when the sound stops the animation ends as well. When 
you're satisfied that all is working as intended, ch(X)se Quit from 
the File menu to end the program. 


Till Next Monto.., 

llie purpose of playing a sound asynchronously is to 
allow sound and animation to occur simultaneously. l*he 
purpose of the caOback routine is to free your program from 
having to somehow predetermine the duration of a sound. 
When a sound ends playing, the callback routine in effect 
tells tlie program that tills is the case. You can prove that the 
callback routine works by opening the standalone 
AsynchPlayer application itself from a resource editor such as 
ResEdit. Give the helicopter snd resource a different ID (any 
ID will do — you're just changing it so that the program 
won't use this resource). Nijw add a dijferent snd resource to 
the program and give it an ID of 12000 — the ID of the snd 
resource the program is expecting to find. Save AsynchPlayer 
and close it. Now run AsynchPlayer and choose Play and 
Move from the Sound menu. Doing that moves the helicopter, 
but now the animation will be of a different length then 
before. Regardless of the length of the new sound, the 
animation ends when the sound ends. 

AsynchPiaycr demoastrates asynchronous sound playing 
using a sound resource. If you want to instead use a sound 
file, read last month's Getting Skirted article to learn about 
sound files and the SndStartFilePlay(} routine, and then read 
the Sound volume of Inside Macintosh to learn about 
completion routines, Like the callback routine used with 
SndPlayO, the completion routine used with SndStartFilePlay() 
executes when a sound has completed playing. In fact, it turns 
oui that the callback routine you just learned alx)ur is a type 
of completion routine. 

Finally, you may want to try asynchronous sound 
playing with a different animation technique. Here, because 
the focus was on sound playing, we used the simple trick of 
repositioning a picture to achieve animation. Try changing 
the AnimateWhileSoundPlaysO function so that it uses 
offscreen bitmaps to achieve smooth, flicker-free animarion 
that doesn't obscure a window's background. You can read 
up on offscreen bitmaps in the Getting Started column In 
both the October and the December issues of last year. 

Tliere are plenty of other sound-related tricks and techniques 
to learn al?out in the Sound volume of Imide Macintash. Go 
ahead and read up on sound, and cxfx*riment with the 
AsynchPlayer ctxle until we cover a new topic next month... 

m 

Interested in writing 
for the magazine? 
Contact us about a 
writer's kit at 
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POWERPLAIUT 

WORKSHOP 


By John C. Dauh, Austin, Texas USA 


Modifying Objects at Runtime in PowerPlant 


A look at PowerPlant’s 
Attachments mechanism 


Welcome! 

One of the thing?; ihiil makes (Jie Mac so 
great and so much fun to use is the ability to 
customize your Mac just the way you like it. 
There ;ire all sorts of cool functional utilities 
like Monaco Tuner/ProFonl and FinderPaj), 
and many ccxsmetic enJiancers like the 
ubiquitous Kaleidoscope, Just how do these 
cool tools do the voodw) that they do 
welP 'Ihrough the magic of trap patching! 
Palcliing traps is a neat way to change the 
runtime I’x^havior of an application aod/or 
the OS itself witlioui having to atlually 
change the application or OS. Tliink of it like 
sulx-lassing to iniplenient new funaiorutlity 
for an objea, bui you didn’t have to siilx:kss 
to actually gain the new functionality — 
sfimetliing cLsc came in at runtime and 
tnodified the object's behavior. 

If that explanation only servcxl to 
ftiilher c:onfuse you, I a(X3logI^e, However, 
by tlie end of this article you will have a 
Ixftter understanding of the statement, YtJu 
see, PowerPlant has a niec:hanism akin to 
patching called Attachments. Attachments 
are a way to modify the nmtime Iiehavior of 
PowerPlant objects, so in a sense it can \yc 
viewt^l as patching. By using PowerPlaiit's 
Attachmc-nis mechanism you c'an extend, 
limit, or otherwise ckinge the Ix^havior of a 
PowerPlant object at runtime, and all 
through a mechanism that's simple yet very 
powerful; in fact the theory of the 


Atiaclmienis mechanism will play a larger role throughout 
PowerPlant in future versions of the framework. 

By the way, if you're curious alx^ut trap patching, check out 
a b<:K)k like Dave Marie's Ultimate Mac Frogrammmg. Dave 
recTuiled Jorg Brown to write the chapter on trap patcfiing, so 
you'll definitely be in g(MKl hands. 

OVEKVIEW 

PowerPlant's Attachment mechanism is comprised of two 
parts: the Attachment's host and I he Attachrncnl itself, 

Attachables 

An objea tliat can hast Attachments is called an Attachable^ 
"llie LAttachable class defines an Aiuichable object, and any class 
that inherits fnaTi [Attachable can have Attaclunents attached to it 
(you cannot attach Attachments to objects that arc not Attachables}. 
Witltin PowerPlant. LAttachable is useil as a virimil Ixcse class for 
some key base objects: LCommander, LEventDispatcher, and LPaae 
(see my iniroduction to PowerPlant article in the December 199B 
MacTtxh or refer to the PtnwrFlant MetnowcTks' official 

tliKumentation on Pow^erPlant, for an explanation of these classes) 


— I LCotwnafwfer |>| 

I m+c IB 

— I IPwlfrl 

Figure 1. LAnachahh class hierarchy. 


Altlic^ugh Figure 1 does not look like much, do not foiget the 
great numl>er of classes that inherit from LCommander and 
LEventDispatcher, and e.spet:ialiy llic multitude of classes that inherit 
fo>m [Pane (liierc^ was just no way to print such a laige hierarchy 
within the constraints of this article). Since these kt'y objeos are 
Attachables, you can begin to see that many of PowerPlant’s key 
liehaviors c'l^in be mixlificd tlitt>ugli tlte use of Attachments. 


John C Daub is one of Metrowerks Corponition’s HtywerPlani engineers. John wonders if you rc'iilly ciire to know quirky 
biographical infonnarion alxiut him, and if so, why? If you really want to kntiw .strange things about John or wish to ask him 
any questions (alx)ui PowerPlant or otherwise), you can reach John via email at lisoi©metrowerks,com. 
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H'he LAttachable class provides all the functionality a host 
needs to manage Attachments. One can AddAttachment() or 
RemoveAttachmentO u> atld or remove Attachments from live 
Attachable's internal list of Attach me nts. If yoifre in a hurry, 
you can call RemoveAllAttachments() to remove all of an 
Attachable's Attachments. Accessors are provided to 
GetDefaultAttachableO and SetDefauitAttachable() (the default 
Attachable is the object to which an Attachment will be 
attached when it is created from a PPob DaiaStream). Finally 
LAttachable provides ExecuteAttachments() as the ever- 
imponant means to allow AttaclmienLs to carry out their task. 
Most of your interactions with LAttachable will be through 
AddAttachmentO (and possibly RemoveAttachmentO), as die rest 
is handled for you widiin PowerPlant itsell. Of course the 
other pan of the equation here are the Attachments 
themselves, so let's take a look at them. 

Attachments 

An Allachment is an abject that can tnodify the mntime 
tehavior of another t>l)jeci without having to modify that object 
itself. Through the use of AltaciimenLs, you can modify how an 
object; handies events, draws or prints, handles clicks and 
keypresses, adju.sLs the cursor, responds to commands and 
actions, and even liow it finishes creating itself. Figiure 2 
pre,seals the Attachment classes provided by PowerPlant. 



an AtUtchment is to modtly the “nomiar l^ehavior of an objett, this 
Attachment execution point fK:curs immediately before tlic liast 
object executes its nomial ct^ursc of action. So just l^efore that 
moase click is given to the Fane object for prcK:es.sing, I he Pane's 
AtUtcltmenLs are given first track at the click. Listing 1 illustrates 
how [his looks in code. 

Listing 1: Attachnicnt execution point __ 

lPane::aidcO 

void 

LPanft:^Clickt 

SM 0 UH{»Dawii£vfi n t ^ inHou se Do wri) 

( 

if ^ linMoiifiefkutfii. delay Select) ( 

Fo r t ToLoca T Po i n 11 iiiH ouseD 0 wn, whe r eLoca 11: 
tlpda l.eCllckComit(iiiMotJseDowrL); 

if (ExecuteAttachiiientaCa^g Click, &inMousKOowii)) I 
ClickSelf (inMoiiaeDown); 

J 

I 

) 


When Click() is called, a little housekeeping is performed, 
then just Ixifore [lie actual handling of the click is to <K‘cur 
(ClickSelfO), the Fane's Attachments exeaire and could veto the 
execution of the Pane's normal click funetitinality. Well look at 
how all of this works in the next section. 

Like tlie LAttachable chis.s, the LAttachment class is also quite 
simple, It contains constructors and a dostructor, as one would 
expeef of a C++ cbiss. One item to note is LAttachment has an 
LStream constructor, which means that Attachment objeas, like 
Pane objects, can be constructed from a PPob DataStream. You 
can edit AlUichments in Constructor, tliey liave class_ID’s, and 
must !k* registered (see U Registrar) if you create your 
AtiachmenLs in iliis manner If youVe worked with Panes in 
PPob’s, this procedure should lx* familiar to you. If you'te not 
familiar with this procedure, if is covered in tiie PouerPkml Book 

There are three* data members in LAttachment: mOwnerHost, 
mMessage, and mExecuteHost (and all three have associated 
GeLSet accessor methods). Hlie first data menilxr, mOwnerHost, 
is a pointer to the Attachment’s host object for easy reference. 
'I’he mMessage data member .'aores the particular message that 
the Anachment is to respond to. Finally, the mExecuteHost 
mcmlxr is a Boolean value which specifies if the host sliould 
continue to execute iLs normal course of action or not. In the 
next section you’ll see how tliese data members come into play. 

The remaining two methods in LAttachment are ExeGute() 
and ExecuteSetf(). This is where all of the aaion hapjxns, so to 
better explain tliem let's lake a kxjk at just how the Attachment 
mechanism actually works. 


Pigure 2 lAftachmmt cla^^ hierarchy. 

The points at which tlic Aitachments are given the opportunity 
to iiKxlify the nmtime behavior of its ho^i ol>jm (i.e, the places 
within PowcTPlant where LAltachable::Ex9CUteAttachments() is 
called) are well defined by tlic PowerPlant API. Since the intent of 


How Does It Work? 

As you saw in the previous .sections, the LAttachable and 
LAttachment classes are fairly simple, and the mechanisms by 
which they arc implemenied and execute are fairly simple as 
well. As mentioned previously, an Attachable iterates its list of 
Aiiachmenrs ai a well-defined point asking them lo execute and 
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pitsfiing them any relevant rnformation the AtUcliment may need 
in order to properiy execute in the given context. Figure 3 
summarizes those pt)ints witliin PowerPIant, 
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Figure 3- Attachmeni execution points. 


When in die course of an application's evenLs it becomes 
necessary to exeaite an Attachment (the Where Called column 
in Figure 3)s the host iterates its list of Attachments asking each 
if it cares to do somediing relevant to the given situation; this is 
done l>y calling the Attachment's Executed meiiiod. Within 
Executed the Attachment checks die message given to it by its 
host; if that message is the same as the Anachment's mMessage 
(or is the special msg^ AnyMessage), then Attachment then calls 
its ExecuteSelfO to do its voodoo. Within ExecuteSetfO the 
Attachment of course does whatever it does (respond to the 
click, handle the event, modify the host’s cosmetics^ etc*), but 
also must specify if upon returning the host should continue to 
execute its normal action or not by calling SetEx©cuteHost{), If 
the Attachment wishes to completely override the host's 
behavior, the Attachment should SetExecuteHost(false)* If the 
Attachment wishes to merely augment the behavior, 
SetExecuteHost(true), Note thi.s only affects the execution of the 
host aaion; if the host has otlier Attachments that have not yet 
executed, they will still exeaite. 

Tliat’s all there is to how the Attachment mechanism works! 
It is such a simple mechanism, but so much can be 
accomplished through it. If you still don’t believe me, diere is an 
example application on the CodeWarrior Reference Cl) (the 
Attacher demo, pan of the PP Mini Demos) and IVe written a 
sampler to accompany this article as well (which should lx: on 
the MacTech web/ftp site), 'llie Attacher demt) shows how the 
mechanics of Attachments work, and my demo can show you all 
of the things you ain do with Attachments. 

_ _WOREONG With Attachments 

Now that you understand how Attachments work, I'm sure 
you want to start to actually work with Attachments, Just as the 


mechanism iLstlf is fairly simple, working with Atmclunents isn't 
very difficult either. ’Ihe two primary areas in which you will 
work with Attachments is how to add/use them within your own 
projects, and how to create your own Attach me nLs. 

Adding Attachments 

There are two ways to add an Attachment to an Atiacliable: on 
the fly or tltrougli a PPob. To add an Attachment on the fly you first 
create the Attachment via its ''parameterized" constniaor, then add 
it to a host by calling the host's AddAttachmentfi method. Listing 2 
illustrates adding an LClipboard Attachment to your Applicarion 
object (CApplication represents your Applic'ation object subclass, and 
remember that LApplication inherits from LCommander, wliich 
inherits from LAttachable). 

Listing 2: Adding an Atta chment o n the fly__ 

CApplksdon: :lnitiali7^ 

void 

CApplication::Initiaiiz^O 
i 

// Create the LCUpbosml Aiudimcm 
LClipboard' theClipAttachment = new LClipboard; 

//AUach it to otir Application objeta 
AddAttachineiit(theCllpAttachrncnt): 

1 

Although some Attachments, like LClipboard must be 
created and added on the fly as above, otlier Attachments can 
be created from a PPob DataStreani (many Attachments support 
both creation meclianisms). Just like you can edit the Panes in 
your PPob's within (Jonstnictor for that wonderful WYSIWYG 
experience, you can add and edit some Attachments in 
Constructor as well. 

' ■ flit HllnAiu 



Figure 4. Editing Attachments in Comiructor. 
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As nieniioned pruviotisly, to crmte your Attachmeni via die 
PPob DataStream, the Altaetimcnt must have an LStream 
constTut-ior anti a class^lD, just like Pane^ dial you create from 
the PPob Da la Stream* As well^ you must register your Attachment 
with URegistrar so the rcanimation process will work correaly 
(again, for more information on PowerPlant's reanimation and 
registration mechanisms, consult the Foii>erPlant Book), If you 
create your Attachments in your PPob's, the Attachment is 
attached to whatever object it is hierarciiically lieneath* In Figure 
4, the LWindowThemeAttachment will be attached to die LWindow; 
the LBeepAttachment is attached to the LStaticText. Ihis is where 
the default attachable comes into play. Take a look at 
LAttachment's LStream constructor and the routines in 
UReanimator to see exactly how the default attachable is used. 

In addition to editing Attachmcncs in PPob's, you can also 
edit die CTYP information for the Attachment’s diemseives. By 
creating your own CTYP’s for your Consmiaor objects, tlieyll 
appear in the Catalog window and can facilitate working in 
Constructor. Figure 5 shows the Constructor CTYP editor. Of 
course you can find more information on creating CTYP's and 
using Constructor in die Constmetar Manual, Metrowerks 
documentation for Constructor. 
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Figure 5- Editing Atiachment CTYP's in Constructor. 


Creating your own Attachments 

With what Tve shown you s far, I hope youVe been able to 
see just how simple it is to work wadi AttachmenLs. But if there is 
anything difficult alxiul Attachments it might be w’riiing your ow'n 
Attachment classes. The process iLsclf Isn't difficult — it's the first 
step of finding the behavior to implement dial might dirow you off 
a bit. Before you fx.*gin to write the Attachment you must design it 
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well. You mast decide wliai liehavior you wish to implement, and 
then how it will fit into the Attachment mechanism; what 
messageCs) to respond to; if the host should execute or not, and 
then under what circumstances to execute or not; if the Attachment 
can lie cjeated from a PPob DataStream; ett:. 

As soon as you have your design and goal(s) for the 
Attachment set, the implementation process is fairly short 
and simple. You need to have at least cme constructor that 
allows the Attachment to be created on the fly. If the 
Attachment can he created from a PPob DataStream you must 
provide an LSIream constructor and class_ID. Then 
implement your ExecuteSelf() to do the Attachment's magic, 
and yoLiYe done! In the implementation of ExecuteSelf(), be 
aware to SetExecuteHostd as needed. And if you wish to add 
I hat finishing touch, create a CTYP file (or your Attachment 
so it can be easily edited within Constructor. 

'lake a look ai the Attachments that PowerPlant provides, 
such as those in UAttachments.cp, There isn’t much to their 
implementation, but as you use Attachments more and more 
you'll find yourself appreciating that simplicity. Conversely, if 
you look at my HCmdButtonAttachment (which is pan of the 
demo application that accompanies this anit:le), you'll see that 
Attachments aren't always lightweight, hut the [X>wer they can 
bring makes them a great uh>I to have in your coolchest. 

Why Use Attachments? 

[f you've made it this far, I hope that you've been able to 
gain an understanding of what Attachments are and ju.st how 
they work within PowerFlant, You've .seen the LAttachabie 
and LAttachment classes, how the AUachments mechanism 
works, and how to build your own Attachments. But there is 
one question that remains: why would you use Attachments? 

Etcmcrnber that AUachments modify the runtime state 
and/or behavior of their liost object. By beitig able to add to, 
remove from, or otherwise modify how an object behaves, you 
can do some nifty stuff ami have a lot of cikIc lo reuse to Ixxjt. 
F()r example, a common feature in Mac applications today Is the 
ability to simulate a mouse click on a button in a dialog with a 
keystroke: For instance, cmd-D could simiiiate a click on the 
^'Don't Save” button in a ""Save Changes” dia]t>g. If you wanted 
to implement this behavior in a button class, you wt^uld 
subclass your main buium class and implement The hinctionaliiy 
to supjiort the kcystroke-as-chck behavior. Yoti did tliis for your 
PiisliBurtoii class, but now you want the same functionality in 
your BevelButton cfa.ss, so you have to reimplement the same 
code all over again. Then you want to have it in your CheckBox 
class, then your RadioButton class, and then you realize you 
want it in so many of your classes lliai it would be better to 
place if into a common parent class, hut then this would break 
l^owerPlani's existing inheritance chains so you would have to 
reimplement every single button widget you used... and you 
give up liecause this is getting ridiculous. 

Considej^ht^ AUachments You are implementing a 
behavior: handle a keystroke as if it w^as a click on a button 


(or any control for that matter). You create an Attachment that 
can intercept msg_KeyPress's, and whose ExecuteSelfO, upon 
receiving the correct keystroke calLs SimulateHotSpotClick(), 
and you've now clicked the button without ever putting your 
hands on your mouse. Punhermore you've factored tliis 
behavior into stand-alone and reu.sat>le code. You can easily 
add this Attachment to your PushButtons, your BevelButton^, 
your Radio Buttons, CheckBoxes, and any other Control you 
might desire. All the same code, no need to repeat nor 
reimplement the code, and no need to subclass anything — 
you can use stock objects. This is essentially what all 
Attachments do, and slightly more specific to this example, 
wliat the HCmdButton Attachment Atiachmem does. 

Attachments are also good for implement tog new 
behaviors for legacy code. PowerPhint's Debugging Classes are 
centered around a menu that is added to your application's 
menubar and provitle.s Functionality to help debug and stress- 
test your application (see the factory Floor column in the 
November, 1998 issue of MacTech fcjr an overview of the 
Debugging Classes), Because the menu is implemented as an 
Attachment (LDebugMenuAttachment) it makes ii quite simple 
to add anti renuwe this functionality from an existing 
application. Furthermore, it enables you to have the Debug 
menu only in the debug liuilds of your application and not in 
your release builds. The modularity and "dropdn” capalnliries 
of AUachments is another strength. 

Ct)NCLLIS10N 

I hope you've lxx?n able to see what AUaclmienis have to 
offer you as you continue you work with l^jwerPlant. If you have 
not used Attachments, tio try the twri denuj applic-acions and read 
over the various Attaclunenl classes' source ctxle, give them a try 
in your owm applications. Most of the Power?lant cx)de that Fve 
written recently has been Attachment IxLsed (e.g. LCMAttachment, 
LDebugMenuAttachment, HURLAttachment), and I find it to lx: one 
of the niftier and more Ilexibie mechanisms That PovvcrPlant has 
to offer. After you're more familiar with Attachments, I’m sure 
you'll also find a place tor them in your toollx^x. What yon c:an do 
witli AUachments is [)reuy limitless, and after yt>ii write yt>ur fust 
Attachment class fm sure you 11 agree with me. 

Until next time,,. Happy programming! 
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PCI FOR MAC 
PROGRAMMERS 


By Larry Barras 


PCI for Mac Programmers 


Understanding the PCI 
Expansion Bus 


Introduction 

[n I995t Apple introduced the PCI 
(Peripheral Component Intcrconnccl) 
expansion bus to the Power Macintosh line, 
replacing the older NiiBus slots, PCI is now 
the dominant bus standard for add-in cards; 
such as disk controllers, video cards, 
network interface cards for desktop PC’s 
and Power Macs. By adopting PCI as the 
standard for expansion slots, Apple 
embraced the wider variety and lower cost 
hardware available on the PC. Almost all PCI 
hardware fijnctions on the Mac, provided 
there Is software to drive the dev!c:e. 

This article is designed to give a 
programmers overview of the PCI bus, 
as implemented in the Macintosh 
computer PCI is a cross-platform 
standard and some concepts of the PCI 
interface will be unfamiliar to Mac 
programmers. Developers who have 
experience on PC's will be unfamiliar 
with some of the Mac's unique features 
as well. Once the concepts and 
differences arc cleared up, tlie actual 
programming is fairly simple. Native Mac 
drivers usually require no assembly 
code, and many useful rotitines are 
provided in the Mac OS. Hopefully, this 
anicle will encourage more developers 
to produce Mac drivers for PCI devices. 


Macintosh PCI Software 

Take any PCI card and plug it in your Mac, and power-up. 
If the card wasn’t specifically made for the Macintosh, chances 
are not much happened. But this Ls not necessarily a bad thing. 
Your Mac did boot after all. The card requires a software driver 
to function on the Mac. lliere are two types of drivers for PCI 
Cards. B(K)t driver is loaded from the PCI Cards firmware and 
executed wlien the Mac hardware in iaitialixed. A Mac specific 
device driver is loaded from the hard drive when the Mac OS is 
initialized. Only cards needed when loading an operating system 
require firmware based drivers. Usually, this means video cards 
and disk controllers for a bootable device. 

Firmware Driver 

Tlie ccjmmon MS-DOS PC booLs with native x86 binary 
code. Writing PC-Com[Datible l^oot code ftjr PCI cards is a difficult 
art. Many aspects of the low-level PC were never well 
doaimented, and many variations exist today. Most expansion 
iilOS ROMS devote a gcx)d portion of code to figuring out what 
kind of hardware it is running on, and how to deal with it. 
Obviotisly, a PowerPC processor cannot directly interpret x86 
code. If a card requires boot time suppon, like disk controllers 
and video cards, the card will need a ROM with Ixjoi ccxle in it. 

Tlie Mac had die opportunity to start with a clean slate. Uie 
boot environment is well defined, and boot-time code need not 
worry about machine-specific conditions. While most PCs look 
die same at boot time, Macs may have tremendous differences in 
things like video adapter addresses, disk controllers, network 
adapters and so on. The raw liardw^are looks different, making it 
difficult to program in die iraditionaf machine-specific manner. 

Open Firmware 

In order to ea.se the card developer's burden, allow for future 
changes in hardware and provide a jxisitive end-ascr exfxjriencc, 
PCI Macs utilize Open Firmware at boot-lime. Open Fiimware is 
based on the Forth language and provides a processor- 
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independent w^iy to implement firmware on expansion cards, 
lasLead of native binary PowerPC or i^iiiary x86 code, Open 
Firmware uses processor independent Forth code. An expansion 
KOM with Open Firmware code on a PCI card can supply 
information about die device to die host computer and can even 
provide basic drivers tor bootstrap devices, until an operating 
system can load and provide OS-specific drivers for the device. 

Open Firmware originalecJ at Sun Micnisystcnis. Sun needed 
a way to build computers and expansion cards that worked on 
all the different processors they were working with. Until Open 
Firmware and the Open Boot spcxrification, computers booted via 
firmware written for a specific processor family. Sun was building 
machines with 68K, Sparc and x86 processors. Previously, every 
card needed firmware coded for each proc^essor family and 
system design. Forth was a natural choice due to its compactness 
and availability on nearly every known processor. 

Open Firmware also lias an interactive Forth console. The 
console is important for developers because it provides a low- 
level interface before tlic Mac ROM is loaded Some Macintosh 
computers use the keyboard and display; other models may 
require a terminal on a serial port to acc:ess the console. Using 
the c:onsole gives the developer a chance to intercept tiie bool 
process and debug code before an operating system or 
something like MacsBug can load. 

When a l^Cl Mac: is hxned, Open Firmware loads from llic 
Mac's ROM and initialijses tlie main board. Open Firmware then 
scans the 1^1 bus for any user-installed cards and scans their 
configunttion registers, 'the configuration registeni indiaire whai 
^c^sou^ces, such as interrupLs and memory addresses, the card needs, 
and wliether there is a Ixxit ROM pmsent. When Open Finnware 
cxxle is executed, unrecogni 2 ed ROM code is simply ignored. 

During the scanning prcx:ess OpenFirmware tiuilds a table 
of devices and resources in tlie system called die Device Tree. 
The information in the Device 'I ree is carried over to the Mac OS 
in the Name Registry'. Mac OS drivers and applications use the 
Name Registry to find things like PCI cards, wlicre tlicy are 
located in memory, what resources they require, where their 
interrupts are serviced, power requirements and so on. 

Apple defines three levels of firmware driver support; no 
finnware, minimal finnware, and full finnware. A card with no 
firmware support on-board leaves generic infoimation in the 
name registiy, and requires a dLsk-bised driver Limited firmware 
includes some Open Firmware code to install specific properties 
in die name registry, allowing your disk-lxtsed driver to positively 
identify your hardware. A Mac OS mntime driver might also be 
included in paitial support scenario, hut such cards will Ix^ 
limited to Ixxiling only tlic Mac 08. Full fimiware support 
includes a Mac OS driver and an Open Firmware driver in Forth 
to allow loading of an alternative operating system like Mac OS 
X Server. An Open Finnwaiie driver makes die device available 
for the entire booting process, even before an operating system 
is loaded. Again, anything that needs to participate in the bcxit 
proLX^ss needs full Open Finnware support. 

Apple recommends developers implement minimal 
firmware suppon, and supply name and resource information, 


but it is by no means required Ordinary PCI cards, like data 
acquisition cards, frame grabbers, and even the popular 3dfx 
Voodoo game cards don't have any ROM at all 

Tlie Name Registry 

All the information that Open Firmware records in the 
Device Tree is passed along to die Mac OS in the Name Registry. 
Ttie Name Registry is a simple rree-like database, which records 
system information, 'the Name Registry is unique to the 
Macintosh and greatly eases driver development. 

On most odier platforms, a PCI driver developer needs to 
know lots of detail about how^ the hardware works. Often one 
must resort to difficiiit techniques in order to configure the 
hardware, reserve memory, determine the CPU speed and so on. 
Under the Mac OS, things are a Jot easier Using the Name 
Registry, your device driver can easily determine whether your 
hardware is present and what res()urees are assigned to it, and 
other inlonnation like the PCI clock frequency. 

The Name Registry provides functions to locate specific 
instances in the device tree, retrieve properties such as addres.s 
space and interrupt-tree location that are allocated to your 
hardware. Your device driver will use tlie Name Registry to 
retrieve the physical and logical addresses, interrupt resources 
and other information about your device. The utility “Display 
Name Registry,” part of Apple's PCI Driver SDK, is useful for 
looking at the Name Registry. 
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PCI FOE Mac Peogeammees 

The first step is \o grasp wfiat PCI offers on any eomptiler 
platform. PCI devices present well-defined means for 
identification, configuration and operation. Identification and 
configuration are handled via a unic|ue addressing mtxle. Since 
the PCI standard is cross-platform, it offers two means for 
transfer of data, lO-mode addressing, common for Intel x86 
pr(K;e.ssor.s, and memory addressing, usually found on other 
processor families like the PowerPC. Either lO or memory- 
mapped addressing may be provided, sometimes both. 
However, due to the popularity of the Intel platform, many 
devices only offer fO-mode addressing. Unlike the Intel family 
proces.sors, tlie PowerPC doesn't offer special lO addressing. 
But, as I will explain later, some clever hardware buill into the 
PowerMac Lakes care of this problem. 

PCI Address Spaces 

Under PCI, there are three relevant address spaces: 
Configuration Space, Memory Space and lO Space. 
Configuration Space is how the card is identified and controlled. 
Memory Space acts like any other physical inejnory address 
space. 10 Spdcv is a special kind of address space, devoted lo 
ii^put/output on some processor tyi>es like die Intel x86. To 
access these address spaces, the Mac provides helpful managers. 
Tfie fund ton calls are documented in “Designing PCI Cards and 
Drivers" from Apple Comjmtcr. 


Configuration registei^ are not mandatory. Vendois am free lo 
implement optional registers as they see fir. Itegisters above 3Fh are 
deviec-spcdfic. Refer lo ifie vendors documenlatitm to determine 
device-sixxdfic legLster functions and whetlier any are implemented. 

The contrtil register lets the hast turn the card on and off, by 
enabling and disabling llie card horn decoding memory or ID 
addresses. Cards are left in a disabled state by default. 

dlie base addieis registers point to a base address in memory 
or 10 spac^^. The hardware on the card will respond lo this base 
address when enabled The lower three bits in die l>asc address 
registers are flags that tell the hast whether the address is in lO or 
memory space, and how much Rxjnr! to reserve for the hardware. 
Tlic flags are tested by writing all ones and all into tlie register 
and examining the lesult. Address space is assigned by writing a 
new value into the base address registers. On the Mac, all of this is 
done for you l>y tlie otxTaling system. Tliere is no need lo reas,sign 
addresses or alter the contents of the kise address registers. 

Ihe ROM address regLsrer is similar to the base address 
registers. Tlie value in tlie ROM address register decides where in 
physical address space the ROM resides. The least significant l>it 
Ls a switch. Setting hit-zero higli enables access to the ROM. Both 
the ROM-tmahle hii of the ROM base register and the memory 
addressing enablc-hil of the command register must lx set Ixfore 
attempting to access the ROM. The Mac’s Expansion Bus Manager 
calls are the only way to acces.s configuraiion legisters on the 
Macintosh. 


Configufation Space 

Configuration Space contains the registers that identify and 
control the card itself. Tills space contains a total of 256 bytes 
for each c'ard I'he PCI stantlatxl ^.lefines pait of these addresses 
foi' control and identifiaition registers. Registers alxive offset 
Ox3F arc dcvicc-sjxcific and may be u.scd by tlic card uj control 
hardware on the card. 


.^1 


2i 


23 


16 


Device ID 


Vendor ID 
Qmmatid 


dass.otKie 


BIST 


Header type | Latency Timer 

Ba.se Address 0 
Ba^ Addiie?i.i 1 


Kevlsion ID 


Cadie Line Size 


Ba^ Address 2 
fese Ad0eas3 


Address 4 
• Base- Address 5 


Subsvtem ID 


CIS pointer 

I Stibsystem Vendor ID 


Expoasion ROM iKLse nddness 






pdibler 
MseM 
p Tniriytil^ [ 




Offset 


oqit 

0^ 

08h 


OGh 

Hh, 

ICb 


ML 

2eh_ 

..m- 






The standard configuraiion registers. 


Memory Space 

Memory .space is familiar to most Mac programmers. 
Traditionally I/O devices on a Macinuxsh am ac:ces,sed Llmxigh fixed 
memory addresses. TliLs is called “meiiioiy'-ma|>f>ed ID.” Serial 
UAR*r diips, video controDers, SCSI controller chips, and other 
devic:e.s are c:ontrolled via regular memory addresses. PQ allows for 
deccxJing of memory address space. This kind of addressing is mast 
common witli devices like fiame-grabtejs and video cards, wliich 
often have frame storage memory onlx>ard 

The card decodes jneniory by tlie physic:al addiess on the 
system bus. Because of virtual memory, tliis is not die same as the 
logical address. Tlie logical address used by software is remapped 
to a physical addres.s on the system’s physical address bus by the 
memory controller. What appears as one contiguous lilock of logical 
memory^ is really scittered diioughout physical memory locatioas. 
The Mac’s Name Jiegisny provides properries defining lx)th the 
phy.sical and logical addresses assigned Lo a PCI device. Also, die 
Driver Services Library provides functions to convert die physical 
address to a logical address and vice versa. 

lO Space 

10 Space may feel unfamiliar to Mac OS programmers. 
Some processor families, notably the Intel x86, use special lO 
mode.s and address to talk to hardware devices. Intel x86 and 
x86-clone computers use lO addressing to communicate with 
pr actically all hardware other than memory . The x86 lO 
.scheme uses a unique addressing mode to send or receive 
data to or from a device. The x86 can address up to 65535 
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devices using a separate ]6-bit fogical-address schemc% aside 
from the memory address-space. This method for handling 
hardware on a PC under DOS or Windows arose partly frtnn 
die heritage of the x86, and partly because of the segmented 
memory unique to the x86. If you've ever installed hardware 
in an Intel-based PC, youVe probably run into the lO addre.ss 
or "ports” as a range of hex numbers that had to be reserved 
for some device. Most I^CI devices are intended for the Intel 
architeetiire and consequently use lO address space. 

The PowerPC processors do noi provide tievice-only 
address modes. Since PCI supports ID cycles, and many PC! 
devices also support lO cycles, this poses a prol)leni. 
Fortunately, the PCI hardware in the Mac synthesizes device- 
lO address cycles. A 64K bloc'k of memory’ address sfiuce is 
set aside for this purpose. The logical addresses are assigned 
automarically by the Mac's boot-up code, and stored as 
profierties under the card's node in the name registry. 

'I'he Hxpansion Bus Manager provides function calls to 
directly genenite lO-device cycles to the PCI bus. However, 
these fimetions carry significant overhead. In every case it is 
better and faster to get the logical address (M'opertics from 
the Name Registry, and let the I’CI controller hardware do all 
the work. The unique lO cycle hardware makes it possible to 
write device drivers completely in C, without resorting to 
assembly language for esoteric addressing nuxles. 

The other really strange thing about lO space is that a 
single address may be 1, 2 or 4 bytes wide. Reailing a 32-l)it 
value at address OxFFOO is im the same as reading four bytes 
at OxFPOO, OxFFfJl, 0xFF02 and C)xFF03 sequentially. Don't 
worry about it, because the hardware handles it all invisildy. 
If the device in question is 8, 16 or 32-biLs wide, just read or 
write to it in that length, even if the very next device register 
is only one address away. It just works. 

Endian Issues 

One problem Mac programmers run into when dealing 
will I PCI is sometliing called iittle-endian." A little-endian 
system defines mulri-byte values so the address |K>inLs to die 
least significant byte, and the last address points to the most 
signifitiint l>ytc. Macintosh computers are all "big-entlian," 
where the address of a multi-byte value is the most significant 
byte, and the least significant byte is the last. An easy way to 
rememlxT which endian is wbich is the sentence, "endian-little 
hate We.” The Expansion Bus Manager provide byte-swapping 
functions, or you can define macros in C which are faster. 
PowerPC and Motorola 68k are Ixilli big-endian processors, 
where as tlie x86 class processors are little-endian. Neither is 
superior to the other, just dilferenr. Big-endian is more intuitive 
and easier to understand, little-endian is luorc difficult to 
envision, and you have to mentally byte-reverse it while 
viewing it in a debugger. Note that the bit ordering does not 
change. A byte looks the same regardless. Only the ordering of 
bytes changes in mulii-byte values. 


'I'he most important thing to remember is not to confuse the 
two and write a big-endian value into something that expecLs 
little-endian, and not to read something in liule-endian and 
evaluate it as hjg-endian. 

Endian example: 

chiir one Byte = 0x0 A; 
ahort = DxOOQB: 

long fourByicS ” OxOOOOOOOC; 

looking at these variables in memory would appear like 
I his in big-endian: 

vacl^ble hyts'vatue 

oneByte +<3 OxOA 

twoBytes fO 0x00 

11 OxOB 

fourHyiDi! -KJ 0x00 
n 0x00 

n DxDO 

n Oxoc 

In little-endian format, the bytes arc arraTigcd like this: 
vflrlahle address byte'value 

oneUyLO +0 OxOA 

twoBytea +0 OxOB 

+1 0x00 

fourBytes fO OxOC 
+1 OxOG 

+2 Ox CIO 

+3 0x00 

Most PCI device documentation specifies three different 
argument sizes; byte, word and double word. These 
correspond to 8-bits, 16 -bits and 32-bit values. Yt)u will run 
into these terms frequently. Kemcmber that the values 

specified are liule-endian in most cases. 

Exampi.e Proc;ram 

Now that the concepts have lieen covered, I will present 
a simple praciical example. The example program will searcli 
for a specific PCI card by its vendor ID, check to sec if the 
card has any ROM on board, and dump the first hundred 
bytes in the ROM to the console. This program will work on 
mcjsi off-lhe-shclf generic PCI cards. This example prohaldy 
will not work on a card developed for the Mac, since these 
u.sually have firmware to set up the name registry with 
information private to the card's driver, instead of generic 
infonnation. But if you borrow a generic card with no ROM, 
or one intended for an Intel PC, diis code will work. 

'Fhe first step is to search for the card by its unit|ue 
Vtmdor ID. We can get the vendor ID from the manufacturer, 
or use a tool like ^'Display Name Registry" from Apple's PCI 
driver SDK. The search is conducted by iterating through the 
name registry until we find a match. 
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// On entry, the parameters are propertyName = “ tame" and pmpertyValue = 

//"pdl 00*1,123'’where 1000 and 125 arc the device 11> codes spedGc to yourtkvice. 
// propertyStec is the length of the C string "pci1000,125". 

//The fimctkKi rciums tlic loimd node in hnindEniry panmeto^ and itmims an emr 
// if an error occurs. 

FindFcopertyWithVslue(const RegFropertyMane 'propertyHaote* 
const void ’propertyValue, 
const RegPropertyValueSize propertySi^e, 
RegfintryiO ’foundEntry) 

I 

RegEntrylter cookie; 

RegEntrylD theEntry; 

RegEntryltecatlonOp iterOp; 

Boolean done; 

OSStatus err “ noErr; 

// Registry searches all work by crcaiing search ctKjkjc, Iterating tiic name trce, 

// then di$|K)sitig llic tokens. 

if first step is to inltialbxif the entry to a known stale. The data types arc opaqtic, so 
// we must do this step. 

; lEegistryEntryTMnit £&thcEntry); 

// create a registry search token or cookie. 

err ;;RegistryEntry11erateCreate{Scookie); 

If (err 1“ noErr) 
return err: 

iterOp “= kRegTterContlnue; 

// search for the desired property by name 

err = ::RegistcyEntrySearch£&ct>okle, IterOp, ktbe&itry* klone* 
propartyName. propertyValue, propertySlze): 

if (Idone (err — noErrU 

( 

•foundEntry = theEntry: 

) 

else if (done) 
err done; 

// after completing a rcgistty search dispose of anything we created. 

::RegistryEnirylDPlflpcjseC&theKntry}: 

::Reg]atryEntryIterateDispose{fiicookie): 

return err; 

I 


Once we find the card by niatchmg the name property, 
the function relume a NtKlefD that we use to refer to that 
instance of the device. If the romhase register shows a KOM 
installed, search the properties for this node lo find the 
logical address lo read it, 

// OK, wc found the card, now lets find out if thete's a ROM on It 

LogicalAddress deviceAddress = OL; 

ByteCount deviceByteCount - 0; 

// 'I he KOM Base athlrcss pointer U in configurarion space, at offset 0x5d. 

err - CPCIUtHni ;GelDovleeLogicalAddress{ fegMyDevice. 

0x30, 

kdeviccAddress, 

&d e ViceByt eCo unt): 

Next, enable the c'ard for memory operation, and enable 
KOM access on the cartl. Use the NodelD, and flip a bit in the 
conliguratjon register, and the lower bit of the rombase register. 

// iwiw enable the card for opcmtimi by setting bit one of the eotnmaml regular 

//The (kimmand register b at offki +4 m coi^uniikja space. 

// Bit fmc cnahks memory addrcs^ig of the canl. HU mo enables tO cydr openatjon 

_ Ji smd Bit two cnabtes Ms Mastering (DMA) tm the catti_ 

err = : :ExpHgrC<}nfigWritaByte (igMyDevice, 

(LogicaiAddteus) 0x02): 


// now enable the loin for operation 

// once the card has memory acce® turned on, wc must specifically tom on Ihc 
// ROM address decoder on by setting bit acm of HOMlkse address register 
err ^ ;:£xpHgrConfi£WriteByte(kgHyDevice, 

(LogicalAddrens) 0x30, 0x01): 

l^st, just read out 100 bytes of memory, .starting from the 
iiase address. 

//VW^U.therc ts a ROM, and wc will print out the first KM) bytes in the ROM. 
if( deviceByteCount > 0 ) 

( 

cout « “We have a ROM. and wo will print out the first 
100 bytes now." << endl; 

cout « "Hole the ROM signature in the first two bytes 
of hex b5 AA, us required in the PCI apeclflcatlmi." 

« endi« endl: 

cout « “Offset Byte Value“ « endl C< endl: 

for( UInt32 i = 0: i < 100; 1++) 

t 

UlntB byte = * ( (lIlntB'ldeviceAddress + 1): 
printft “%d \t\t %02)I \ti*, i* byte) ; 

1 

I 

Conclusion 

Mosi PCI c:ards will work in the Macintosh, if you write a 
driver to support ti. Tlic Mac's unicjue hardware and well 
designed driver support software make ihc task of writing 
drivers far simpler than writing drivers on oilier plaifonns. 
Because many interesting PCI cards are available for the 
Windows/Intel PC, Mac developers should see this as an 
opportunity to exploit low-cost PCI hardware by writing drivers 
and support code so these devices work on the Mac. 
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Want to know what products ar^ i 
available for Mac OS development? - • 
Check out DeYek>per OepoP 
<|ittp://vwimdevdeg^^ 
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PROGRAMMIMG 

TECHNIQUES 


by Kas Ibomas 


Natural Object Rotation 
without Quaternions 


The usual way of doing 
free-rolalions isn’t 
necessarily the best way. 


Introduction 

User interface design in 30 app!ianiorus 
remains a difficult area. The problem of how 
best to allow user access to features like 
object, face, and vertex seleaion; translation, 
scaling, and rotation; and seleaion and 
movement of ligliis and atmera, Ls still 
largely an ofxjn question. Most interfaces ^ire 
liiglily modal and rely on the use of 
unfamiliar widgets, glyphs, or ic-oas. Most 
end-users, alas, remain confused. 

One of the most fundamental 
operations in 3D design is object roiatkyn. 
This may, in fact, be tbe single most 
important mtxie of object manipulation. 
Users expect to be able to rotate objects 
at will. Ohis is why, lor example, the 
Apple 3n Viewer supports free mtation as 
the default mouse-drag behavior.) Most 
interfaces, the 3D Viewer's included, 
support simultaneous rotation on x- and 
y-axes, keyed to mouse horizontal and 
vertical movements. That is to say, side- 
to-side displacement of the mouse resulis 
in an apparent rotation of the 3D object 
about the yaw (y) axis, while up-and- 
down Cor fore-and-aft) dragging of the 
mouse causes rotation on die pitch (x) 
axis. Since the mouse has only two 


degrees of freedom, z-axis rotations arc ignored. The code for 
aLiiicving the rotation usually looks something like this: 

dclta_x = iiioij^ePtNew.h - movisePtOld.h: 
dclla_j? ^ (iKiusePtNew,v ■ mauspPtOld.v: 

// now rotate on ihc X axh by ihr amount of vertkaJ motioD (dy) and 
// mwte it»c object around tlR' by the anioiuit of btcral mot ion (dx): 

RotateObjeetC delta_y. d[elta_x. 0.0 ): 

The RotaleObject function typically stuffs the (appropriately 
scaled) argument values into a 4X4 rotation matrix and performs 
a matrix multiplication with the object's global rotation matrix" 
to calculate the new orientation of die object, 

Tlie problem with this approach is that object motion is not 
constrained to just the x- and y-axes. Cross-coupling of axis 
rotations inevitably causes stimc mcjiion of the object about die 
third (z) axis. Tliis well-known effect (which is responsible for 
“giiiibal lock") arises because the three degrees of rotational 
freedom that would seem to be available in a Cane.sian 
e£x>rdinate system are not truly independent. Translations in 
Cartesian 3-space are independent, because they combine (via 
vector addition) in commutative fashion. Rotations on Cartesian 
axes are not independent, liecause their combination (via 
matrix multiplication) is nor commutative. 

The reason this is a problem for user-interface design is 
that mixed x/y-axis object rotation (using the kind of code 
shown above) gives confusing feedback to the user. Some z- 
axis crossover always occurs. The unexpected z-axis rotation 
that occurs is counterintuitive in and of itself; but there is also 
the very serious problem of poinling-dcvicc hysteresis: This 
refers to a situation where rotational positioning of objects 
depends not only on the final position of the mouse or 
trackball, but tbe path it took getting there. In other words, 
when you drag the mouse from Point A to Point B, the final 
orientation of the object can be different each time depending 
on the exact path the cursor tcxik. Dragging the c:ursor back 


Kas Thomas <ttio@earrhlink.tiet> has lieen a Macintosh user .since 19H4 and has lieen programming in C on the Mac sinc’e 
1^. He holds U.S. l*ateni No. 5,229,76g for a liigh-spee^l tlaia txinipression algorithm and Ls die author of a QD3l>-powered 
Phottxshop® plug-in, Callisto 1.0, available at http; //users. aol.eom/Callisto3D. 
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IQ PqiiiI a may or may not restore the object lo its original 
position, (Usually it does not.) 

This behavior goes against Applets own Quitikdraw’’’^ 3^ 
User Tnterface Guidelines (as publislied in the original SDK for 
QD3D), where it is stated: “I'o support interaction, the application 
miLst comfflermmt iwry mar action imlb aftproljriatafaeclhack'* 

It’s hand to conceive of how a pointing device with serious 
built-in hysteresis and a propensity to generate imconinianded 
third-axis rr^tations on be sakl to provide ""appropriate feedback.” 

The Way O ut 

Because of programmers’ traditional slavish adlierence to 
Euler-angle rotation methtxls, there would seem, at first, to tx! 
no way out of die “uncominanded z-rotation” dileinma. But in 
faa, as first pointed out by Ken Shoemake (at SIGGRAPH ^85), 
tjuaternion algebra provides a solution lo this very problem. 

Quaternions were conceived (as an extension of complex 
numbers to higher dimensions) in 1843 by the mathematician 
William Hamilton. They bear a strong resemblance to complex 
numbers — that Is, nonilxirs of the form a + bi^ where a is a 
real number and hi is the sO“Calied imaginary term (i being 
equivalent to the square root of -I). A quaternion is a four- 
component number (hence the name) of the form; 

q = a. + bl + cj + dk 

Where = -T Just as complex numbers can !>e 

wriiicn as ordered pairs (a, hi), quaiernit>ns can be considered 
as a grouping of a scalar quantity widi a vector cjuantity, ^ - (s, 
V ) where s is the scalar component and is a 3D vector in ijk- 
space. In this view of things, an ordinaiy 3 D vector can he 
ct>nsidered a kind of degenerate quaternion; that is, a quaternion 
with a zero-valued scalar component. Such a purc-vccior 
quaternion is known as a “pure quaternion.” Also, just as 
ordinary vectors can be normaitzed (a process in which the 
coniponenLs of the vector are scaled by the vccior’s magnitude) 
to give unit vectors, quaternions can be nonnalized to give “unit 
quaternions.” Space doesn't permit a full discussion of 
quaternion algebra here, [)iil the resemf)lances to vector algehni 
and complex-number aridimetic are extensive, (See Cliapter 15 
of Advanced Animadon and Refidering Techni<]ues by Watt, or 
a good math text, for fun her details.) 

Perhaps tlie most intuitive way to consider quaternions is to 
regard them as pairings of rotational angles with rotational axes. 
The scalar part of a quaternion can be .seen as the amount of 
rotation, while the vector part; represents the axis on which the 
rotation takes place. A purc-vector quaternion Is thus an axt.s 
without a specified rotation. 

The significance of quaternion algebra for graphics 
programmers lies in the fact tiiat naaiions can be t:alc’ulaied in a 
way that makes arc intervals add and subtraci like vectors, whicli 
is to say commutarively. "Ihis is because quaternions assume a 
parametrization of coordinate .space based on the natural 
rotational axes of objecLs, In lhc\quaiem view of thin g s, two 
arbirrary points A and B on a unit sphere are separated by an 
angular interval that cm be expressed in a single quaternion, A 


third point C c^an l>e expressed in Lenns of its am-irUerval frtjm A 
or B by the appropriate quaternion. Owing to the way 
qualernion,s parametrize rotation space, the quaternion 
expressing the rotation from A Lo C is just the sum of the 
quaternions giving A-toB and B-to-C. Contrast this with a Euler- 
angle representation of “rotation space" in which going from 
ix)int A to point B requires fixed RJtalions on x, y , and z axes. 
There are generally no fewer tlian 12 different ways of combining 
Euler angles to achieve a desired rotation in x-y-z space. 

If ([uaiernion algebra has a downside, other than 
unfamiliarity, it’s that most graphics systems are designed around 
matrix math. Even if rotations were to be represented wholly in 
terms of quaternion.s, scalings and translations are typically done 
witli matrices, and for convenience it is usually the case dial 
individual matrices are combined into one final “object 
manipulation" matrix that simultaneously performs translations, 
scaling, and rotation. So the grapliics programmer who wants to 
use quaternions to control rotations usually is forced to convert 
between quaternion and matrix representations on a frequent 
basis. The necessary conversion ccxle in turn adds to program 
size and computational overhead — two things most graphics 
programs don’t need more of, 

The Piire-Ve(T(>r Ai.ternative 

It's not striedy necessary to use quaternion madi to achieve 
hysteresis-free mouse or trackball rotation of screen objects. 
Hy.sferesi.s-free rotations can be set up using ordinary vector 
madi, if we apply the lessons learned from cjuatemion space 
parametrization. The main idea is to think in terms of arc 
intervals. If we have two arbitrary points A and B on the surface 
of a unit sphere, the most natural way to get from A to B is to 
rotate the .sphere so dial A follows the shortest path (or 
geodesic) from A to B. Thus the rotation occurs in the plane of 
the geodesic, if a = ( x.^, and b = (X|,,y|„zjj) are the position 
vectors of the points, the axis of rotation is given by a 5 b. The 
angle of the rotation can lx: obtained from cos^^ (a O b). 

How do we get from 2D mouse ccKirdinates to 3D rotations? 
We const met a psendo-3D coordinate space as follows. (This i.s 
essenrially die mediod of Shoemake in Graphic Gems IV^ p. 176.) 
Superimpexse an imaginary sphere on our 3D objea such that the 
center of the sphere is at the po.sition vector c = (screen_x, 
screen_y, 0), where screen_x and screen_y are Liie local screen 
coordinates of liie center of the object* We assume that any 
mouse-downs will happen on the surface of our imaginary 
sphere, which has a r:tdius of r pixels. To get the 3 D po.sition 
vector ni 0 = (mx, my. mz) of' the |x>int on the s[>herc wlicrc a 
mouse-down cxrcurs, we make the assumption that 

mx ” (float) (mousel>own_x - screen.x)/r: 
ttiy ^ (floaL) (iDouj^thnown^y - scrGi?n_y]l/r: 
mz “ sqtt (1.0- (mx * jnx + my * my) ): 

Note dlat in. J^ialing mx arLd_ niy .by th e sphere radius . we_end_ 
up with a normalized veaor — a position veaor on a unit sphere. 
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We now track the moose and calculate the components of 
a “current mouse position” vector, ciUq = Ccmx, cmy, cmz) by 
the same method; 

Cra\ = Cfl(»at) (cuiTCOtMtmsc_jt - scrccn^xyi; 
cmy = (float) <aimMitM(H»sc_y - scrttm_y>/f; 
cmx ^ «qn( LO - (cmx * am + coiy * any)): 

Point A LS now i% and Point B Ls cm^ . The axis of rotation 
is obtained as the cross produa of the two veaors. The angular 
interval is ohtiinable from the dot product of the two. (Recall 
that tlic dot product of any two normalized vectors is the casine 
of the angle formed by them.) 

Code listing No* 1 shows the function Vectorize, which 
converts a mouse hit to a 30 position vector on the unit sphere. 
The code is extremely siraiglilforward and needs little commcnl 
except to note that it is crucial to check for mouse out-of-range 
conditions, ff a mouse hit occurs outside the radius of the 
imaginary sphere, youll lx: trying to get the square rcKK of a 
negative number and sqrtO will return NAN (not a number). 
Note that the mdius value is entirely arbitrary. It's up to you to 
decide how wide a “sphere of influence" to give your user. For 
consistency, we passed the radius argument as a float, l>ut it will 
generally be some integral number of pixels Ce*g., the greater of 
the view pane witkh or height). Note also that we multiply y by 
minus-one, to correct for the fact that in screen space the y-axis 
has a positive downward direction and negative upward 
direction, just tlie opposite of ordinary 3D space. 

Listing 1 : VectorizeO _ 

VectoitMO 

// Cmitc a 30 pfHittim veam nn a unit s^ptiere based on 
// mouse hitPt, sphere's screen origin, and sphere radius in 
// pixels, Rcnim zero on success or noD-zero if hit point 
// was outside the sphcrc.This routine uses Quickhaw™ 3D 
// and assufoes (Jut the rclev^ QD30 headers and tibrary 
// files have been included. Also need to ^indude <madi.h>. 


C(xle Listing No. 2 shows how we can use Quickdmw™ 3D 
routines to perform a zero-hysteresis rotation of a 3D objea with 
the aid of the vectors generated by Veaorize(). Note that in 
Listing 2, we assume tliat tlic 3D object we'm going to rotate is 
contained in the fModel field of the global gDocument, an instance 
of a DocymentRec, which is a custom data stnictufe. (ibis should 
look familiar to anyone wlio lias read the sample code in the 
Quickdraw™ 3D SDK.) Tlie gDoeument struct also holds a pointer 
to our objea's rotation transform, which kept in fRotation. i'he 
aigLimcnts vl and v2 arc just the position vectors of Point A and 
Point B (the starting and ending points of our geodesic). To save 
time, we stan by checking the dot-product of these two vectors 
to see if it's equal to unity, in which C!ase the angle l>etween them 
is zero and we obviously needn't conlinoe. A.s.su[Tiing the dot- 
produa is not zero, we next calculate tlie cioss product of die 
two input vectors. (Quickdraw™ 3D has an extensive math-utility 
library for performing vector calcuktioas.) The nTxs.s prtxlua 
gives us our rotational axis. Note; We nortnalize die result of the 
cRxss to avoid unintendonally rescaling our objea duration the 
easuing matrix miation. (Recull that the cross produa is a veaor 
whose magnitiuie is governed by the sine of die angle of die two 
input veaors. If we don*t keep the magniaide equal to one. we 
might accidentally rescale our objea!) 

Once we liave a rotational axis and an angular displacement 
value, we can make use of Quickdraw™ 3D’s handy 
Q3Matrix4x4_SetRotateAboutAxis funaion, which will custom- 
rnakc a 4X4 rotation matrix for us that achieves exactly the 
rotation we want. Tliis function takes, as arguments, a pointer to 
a (destinadon) matrix structure, a pointer to an origin point for 
the rotadon, a priinter tc) an c>rientation vector for the axis of 
rotation, and an angle in radians. All wc liave to do Ls stuff the 
appropriate values into these arguments, multiply die resulting 
“rotate on axis" matrix by our 3D objea's stored rotation matrix, 
and draw the ot)jccl. 


fdefine BOUNDS ERR ID 

long Vectorlmi 
Point *hlt. 

Point 'origin, 
float radius, 

TQ3Vector3D *vec ) 

{ 

float modulus: 

X = (float)Ehit->L - origin“>h)/radius: 
y ” (float) (hit->v ■ origln'>v)/cadtufi: 

y * = ' 1.0: // compensatt; for mvened" screen y ajtls! 


Listing 2: ZeroHysteresisRotationO 

Zouliystat^nsRoLuiionO 

// Vwm two 5D veaors rtpresaiUng the pwsiiions of 
// pomo» on i uckit sphere, calcuLuc an axis of rotation 
// :uid an amount of rotation sudi that Point A can he 
// moveil along a geodcsk: to Point fl. 

// CAUTION: Errorcbccking omitted for ebrity. 

void ZeroHysteresisRotationE TQ3Vector3D vl, T(ilVectoc3I) v2 ) 

{ 

TQ3Vector3D ctoe^; 

TQIMat rixAx/i thejMatrlx: 

TQ^Polrtm orl£ - ( 0 ., 0 ., 0 . I? 

float dot*angle: 


modlilua * x*x + y*y: 


dot - Q3Vectoc3D_Dor( Sivl* SiV2 ): 


if (modulus > 1.) //cMiLSiik radius! 

return BOUNDS_ERR: 


if (dot “ 1.0) 
return: 


// ntnhing to do 


z “ sqrt(l. * (x*x » y*y) ): //awnputr fictilinus T value 
Q3Vector3D_Sci ( vec. x, y. k ); // compute pscuck>'5D mouse posttioa 
return OL: 


Cl3Vector3D_Cross( frvl. &v2. &croas ): //axb of rotation 

Q3Vectoi:3D_^oniiallze( Across, jrcroES ): 

angle “ Z.'acosC dot ): //angle of routioo 

// SCI up a PHation apjtmd our diosen axis... 
(i3Hatrix/jx4_SetRotateAboutAx 1 a (ithoMat r i x. 

^rig. Across* anglo): 
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Q3Matrijt4x4_Multiply ( SigDorument. fl?otation, 

^llhoHatrix. 

S( gDocumeii L. f Eo tat ion): // multiply 

DocumentDrawC fisgDocument ) : //draw 

J 

Note that the rotation angle obtained from the call to 
acosQ is multiplied by 2. Tliis is not a sensitivity adjustment 
value! (if you want to give the user a sensitivity adjustment 
for his mouse rotations, scale the radius of the imaginary 
sphere on which our Point A/Point R geodesic is drawn. 
Don't adjust ihe rolation angle.) The muitiply-by-2 is 
necessary in order to make the rotations behave according to 
the laws of quaternion algebra. If we change this value, our 
rotations will not commute and we will have reintroduced 
hysteresis or axis-crossmodulalion, which we don’t want. 

To track mouse movements, we simply need to call a 
function like the one in Listing 3 frfsm our event loop 
(assuming weVc in frcc-rolale mode and not object- 
translation mode or some other mode). Our screen object 
will now rotate in accordance with gerxlesic-addilion laws — 
and user expectaiions. 

Listing 3: FreeRotateWithMoiiseC) _ 

i-rccRoutc WiihM< >nscO 

// Call this fiinction frtim Uic main cvcnl luap U> 

// frce^foLiLicinsi of 313 iibjtttii 

// ihc mouse aciitm radius in pixels; 

^define RAD1US_VALUK 300.0 

void FreeRotateWithMouseivoid) 

I 

Point now, oldPt, centeri 

WludQwPlr win FrontWJndowt): 

float radius = MDIUS_VALUE; 

TQ3VGCtor3Dv],v2r 
long err; 

GetMouae{ ioldPt ): 

con ter, in ” (win ^portReot. right - win-]>portRect. left)/2: 

center.v = twin->portRect.botiom - win->porLRcct,top)/2: 

while (StillDownO) 

I 

GetMouseC Snow ) ; 

ett ^ VeciorizG(SioldPt. ^center, RAhTUS VALUE, kvi ): 
err += VecttiE:ii:e{SfUow, 5icenlei:, llAniIIS_VALIJE, &v2 ); 

if (lerr) 

ZeroMysteresisRotationl vL*v2 ): 
oldPt =■ now; 

J 

I 


Does It Really Work? 

The proof, as diey say, is in the pudding. The best way to 
judge the desirability of hysteresis-free object rotations is to 
experience the phenomenon for yourself. A sample program 
using the ab()vy_ r 3 )!JLmes (and alst) the more conyentipnal 
Euler^angle matrix rotations, for comparison purposes^) is 


available at Counting to <http://www.mactech,com>. Our sample 
program, FreeRotate, has menu options that lei you choose 
Kuler_XY, Euler_XZ, or Euler_Y2 rotation styles tn addition to 
the Zero-Hysteresis method outlined above. If you try the four 
methods, you'll surely agree that the Euier-angle methods pale 
by comparison to the zero-hysteresis ‘‘geodesic arc” method. 
The Zero-Hysteresis method gives an all-around superior user 
experience, because: 

T Objects turn in the direction of mouse travel, and in direct 
proportion to mouse travel, as expected. 

2. An object's final orientation depends on the /malposition 
of the mouse, but not on how the mouse got there. 

3. There is no permanent penalty for dragging the mouse 
“the wrong way" — returning it to the starting point 
always restores the object's original orientation. (The 
incremental angular error accumulation of mouse 
dragging is, for once, reversible.) 

'fhe Euler_XY method obeys the first lest but fails the 
other two. (The other Euler methods fare even worse.) 

A simple test: Load a 3DMF teapot in the Simpiel'exr 
Viewer, click on the center of the model, and drag the mouse 
in three counterclockwise circles of ever greater radius, clien 
reliim the mouse to where you originally clicked. If you do 
tills in any current version of Apple’s 3D Viewer, you will end 
up with the teapot spout-down — i.e., having experienced a 
net counterclockwise rotation on ifie z-axis; it is no longer in 
its tsriginal orientation. ('Itie exact amount of z-rotation 
depends on how far away from center you moved the mouse.) 

With zero-hysteresis rotation, you can make as many 
random circles with the mouse as you want^ returning it to 
center always returns the teapot to its original orienration. 

Conclusion 

Engineering a solid, correct-feeling User Interface for iD 
programs is difficult, in part because of the challenges 
inherent in implemeniing ihree-dimensional object 
manipulations with a two-degree-of-lTeedom pointing device 
(such as the mouse or trackball). But this hardly means we 
should settle for countermmhive pointing-device feedback, 
especially if something better is available. In the case of 
Euier-angle free rotations, something better is available; 
namely, rotation along geodesics. 

Because free rotations are central to the 3D user 
experience, it is crucial to implement diis feature in the best, 
most linear, most intuitive and natural-feeling (to the user) 
manner possible. I'hat means implementing zerodiysicresis 
rotarions — rotations along geodesies. Ki 
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EXPLAIN 


By Dave Evans and Mark Turner 


Counting to X 


Ten Steps Toward Carbon 
Compatibility 


Carbon Ls ihc basic element tn 
Apple’s plan to take Mac OS applications 
into the next oiillennium. Together with 
Mac OS X, Carbon delivers exactly what 
developers have been asking ft>r — an 
easy way of allowing Mac applications 
u> enjoy all the advantages of a memory 
protected, preemptively scheduled, 
multitasking operating system. 

A preliminary version of the Carbon 
SDK has already been released to 
members of the Apple Developer Program, 
hut even if you’re not a member, there’s a 
lot you can do now to make your 
transition to Mac OS X easier. And the 
good news is that these changes will alsi> 
provide a better experience for your 
customers running Mac OS 8. In this article 
we’Ii discuss ten steps you can lake to 
prepare for Carbon. But first, a brief 
overview of Carbon and why it’s important 
that you prepare for it now. 

Carbon Defined 

Carbon is a set of APIs that run on 
both Mac OS 8 and Mac OS X. It’s a 
hybrid that includes over 70 percent of 
Lite existing Mac OS APIs, covering 
about 95 percent of the functions used 
by applications. Because it includes 
most of the functions you rely on today, 
converting to Carbon is relatively 


painless. And by weeding out or modifying certain difficult- 
UKsuppon functions, Carbon provides a more streamlined 
and stable base for application dcvelt>pment. 

What this means for you is that by making a small 
investment in Carbon, your programs will gain these benefits 
when running under Mac OS X: 

• Greater stability. 

Preemptive tnoltitasking and protected address spaces will 
help prevent other people's bugs from crashing your 
appiication. (It goes without saying that tlicre arc no bugs 
in your code!) 

• Improved responsiveness. 

Because ail applications are guaranteed proce.s.sing time 
through preemptive scheduling, you don’t have to worry 
about being locked out by another program that’s hogging 
the CPU. And since Mac OS X and Cairbon are 100% 
PowerPC native, there’s no 68K emulation and no modc- 
.Hwitching overhead to slow down your applications. 

• Efficient use of system resources. 

Your application isn’t limited to a fixed heap size and can 
dynamically allocate memory and other system resources 
l)ased on actual need.s rather than predetermined values. 

Although your current applications will continue to run 
unmodified in Mac OS X through a technology code-named the 
Blue Box, they won’t enjoy all the performance and reliability 
enhancements of Mac OS X until you update them for Cart>on. 

That all sounds great, but the best part is that you don’t 
have to wait for Mac OS X to appreciate the benefits of 
Carbon. By cleaning up old code and adopting Carbon- 
compatible APIs, your applications w^iil run more reliably on 


Dave Evans is an engineer on the Carbon team and Mark Turner is a technical writer at Apple Computer. 
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today’s Mac OS while taking advantage of the latest Apple 
technologies and human interface improvements. 

Nothing’s free in this world, and Carbon is no exception. 
It 11 cost you about two wrecks work to update a typical 
application. But by preparing for Carbon now, your 
applications will not only run better on Mac OS 8, they'll be 
ready to rock when Mac OS X rolls out later this year 

Carbon Coding 

Okay, time to roll up your sleeves, fire up your Mac, and 
give your app a tune-up, 

h Read the Carbon Paper 

Before you change a single line of code, you should 
read Transitioning to Mac 05 X: An Oi/erview of the Carbon 
Programming Interface. This white paper explains why 
Carbon is so important, and defines Apple’s goals for the 
project. It also lists the expected level of support for all 
existing Mac OS APIs. Youll find the Carbon Paper, and a lot 
of other helpful information, on the Carbon web site at 
http://devetoper.apple.com/macosxycarbon/. 

While you're visiting the web site, be sure to check out 
the official Carbon Specification for the most up-to-date list 
of supported APIs, Then download the Carbon Dater tool, 
because we’re going to talk about U next. 


Apple is working very hard to make the Caiftx>n traasition 
an easy one, and the Carbon Dater statistics l>car tliis out. As 
Figure 1 shows, of the thousands of applications tested, the 
average compliance level is over 95 percent. 


Parctrit^Qi Hun)«er«f 
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Figure 1 , Carbon Dater Results 

For step-by-step irLstmaiorLS on running Carbon Dater and 
interpreting the results, see the Getting Started column, Carbon: 
CeUing Ready for Mac 05X, in the January 1999 issue of MacTech. 


IL Run Carbon Dater 

If you completed Step 1, you already know that Apple's 
Carbon Dater tool provides a detailed report of your code's 
current Carbon compliance level. (If you didn’t follow Step 1, 
shame on you! Go back and read the Carbon Paper.) 

Carbon Dater works by examining PEF containers in 
application binaries and CFM libraries. Ti compares the list of 
Mac OS symbt^ls yi>ur code imports against Apple's database 
of Carbon-supported functions and issues a spiffy report 
formatted in Hl'ML. 

In addition to analyzing your Mac OS function calls, 
CarbtJo Dater tries to identify any attempts to read or write 
directly to low-memory, and it also reports if any of your 
resources have the system heap bit set. Carbon applications 
don't have access to die system heap in Mac OS X, so you 
can't load resources there. 

As we discuss in Step JV, all access to low-memory system 
global ckita must be through accessor functions. Because many 
of today's accessor functions are simply macros that 
implement a load or store to memory, Carbon Dater can't 
determine if your low-memory accesses are illegal — it’s up to 
you to make sure you're using die proper functions. 


m. Use the Most Recent Universal 1 leaders 

Okay, so you've read up on Carbon, tested your 
application, and most likely discovered that it’s pretty close to 
95 percent compatible. Whal do you do next? Sync up with 
the latest Universal Header files! 

You can start by downloading the current headers from 
Apple's web site. As of this writing, Apple has released version 
3.2 of the Universal Headers, incorporating all the new 
technologies in Mac OS 8.5. In addition to new APIs, there are 
minor changes Irom previous 3.x versions. For example, the 
KeyMap definition has changed from an array of longs to an 
array of Uint32 values. Be sure to read the release notes for more 
infonnation about what has changed. 

After successfully building your application on the cuneni 
headers, you should download and install the Carbon headers. 
The Carlion headers incorporate addilioiial changes, including 
new conditionals to use wlien building Carbon applications and 
new APIs to replace some o( the older functions that aren't 
supported in Carlxm. 

The Carbon lieaders eventually will be rolled into future 
versions of the Universal Headers, and you can use them for 
l^utlding non-Carbon applications uxlay. To build a Carbon 
applic'ation, just add the following statement to one of your 
source files before including any of the Carbon headers: 

^define TARGET_CARBON I 
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Tlie TARGET_CARBON a^nditkmal specifies that the 
included header files should allow only Carbon-compatible APIs 
and data structui^. When you throw this switch and rebuild, 
youYe likely to a number of errors and warnings from the 
compiler. For now, stifle the urge to liack your way through 
those errors. Youll save yourself a lot of time if you read the rest 
of this article and address each issue methodically. 

IV, Avoid Using Low Memory Globals 

Low-memory globals are system and application global 
data located below die system heap in Mac OS 8. They 
typically fall between the hexadecimal addresses $100 and 
$2800. Since the transition to PowerPC, Apple has provided 
accessor routines for getting and setting these global variables. 
Prior to that, you w'ould simply dereference die aljst^luie 
addre.ss of the global to modify it. 

Carlxin applicatioas .still have access to many of the low- 
memory globals. although in some cases the scope and impact of 
the global has changed. But in all cases, Carbon applications must 
use die supplied accessor routines to examine or change global 
variables. Attempting to access them directly with an absolute 
address will crash your application when running on Mac OS X. 

The complete list of low-memory globals supported in 
Carbon hasn’t been published yet, but youll he bener prepared if 
you take the time now to review your use of low memory. Tlie 
transition to Carbon will be easier if' you follow these guidelines; 

• Use high-ievc! Toolbox calls instead of low-memory 
accessors whenever possible. 

• !f a high-level call is not available, use an accessor function. 

• Rely on global data only from Toolbox managers 
supponed in Carbon. 

Make your best guess about the last point until Apple 
publishes a definitive list. For example, because the driver-related 
calls in the Device Manager are not supported in Carlx^n, low- 
memory accessors like LMGetUTableBase are not likely to be 
available. Similarly, direct accx^ss in hardware Ls nor supported in 
Carbon, so calls like LMGetVIA will no longer lx: useful 

Some low-memory accessors have Toolbox equivalents — 
applications mast switch to these Toolbox calls instead. For 
example, use GetMouse instead of LMGetMouse, Ticks instead of 
LMGetTIcks, and MemError ii^stead of LMGetMemErr, 

V, Go Native 

Because Carbon requires 100% native PowerPC cxxle, you 
must remove any dependencies on 68K instruaions. Unless you 
iiave written your application entirely in assembly language, this 
should not be a big issue for your main application code. Where 
you are more likely to have 68K code is in custom definition 
prtxedures (defprocs) and plug-ins. 

Custom dcTprtxis (for example, MDFFs, CDF!Fs, and LDHFs) 
must be compiled as PowerPC code and no longer can lx: sioa^d 
in resources. Carbon will introduce new variants of CreateWindow 


and similar calls (NewControl, NewMenu. etc.) that will take a 
universal ProcRr for a definition procedure. Instead of providing 
a WDEF in a resource, you would instead call a new Toolbox 
routine that might look something like tliis: 

OSStatue CteateCustomWiudawCWindowClasa vindfiwClafls. 

WindovAttribirtefi attributes, const Rect 'bounds, 

WindowDefUPP custojnProc, WlndowPtr 'outWindow); 

For all Mac OS funciioas that expect definition procedures 
in resources today, there will !x' new routines to specify the 
custom procedure. But before you spend a lot of time updating 
old defprocs, you .should think about whether there is any need 
to continue rolling your own interface elements. New APIs like 
the Appearance Manager and Navigation Services may provide 
all the features you want. 

That said, if you want in compile custom defprrKs into your 
code today, the following snippet shows a clever way to do it. 
This will not work in the fumre for Carbon applications on Mac 
OS X, but for a Mac OS 8 application, it will allow defprocs in 
native code using stub routines as shown here. 

// Llsinu a 6-5)14: stub WDEF resource (ID I2fi ftjr example), 

// filNn a 6Bnxfl 'jmp’ opctxk and the address of a UPP 
// to the native definition proc. Note: NcwWinctowDcfProc 
// will allocate memory bi Mac OS 8.x 


"IN JUST A FEW SECONDS I'VE SUCCESSFULLY TRACKED 
DOWN A MEMORY CORRUPTION BUO THAT HAS BEEN ELUD¬ 
ING ME FOR ABOUT 3 MONTHS, FANTASTIC i*)" 
-BRYAN CHRISTIANSON- 
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Handle theStub: 

tbeStub “ GetRe^ourceC'WDEF'. izaj: 
if (theStub && *theStub) 

I 

WindovDefUPP theProeUPP; 

theProcUPP * NcwWindowDcfProc(fiHyWDEF) i 
•((long •) (‘theStub + 2)) = theProcUPPi 
‘((short ') ‘theStub) = 0x4KF9; 

//Wc just ro<Jc, flush ihr emulator cache 

FIushCodeCacheEange(‘theStub. 6)^ 

1 


VL Get ll^cd tfi Opaque Taalbox Data Stmctitres 

Some familiar Tcxjlbox data structures are not directly 
accessible in Carbon- There are new functions to inspect the 
contents of these opaque structures. For example, you can no 
longer dereference a CGrafPtr to inspect the contents of the 
GrafPort structure- Instead of addressing a port bounds 
rectangle directly with &myport->bounds, you must call the 
new routine GetPortBounds(myport, &inyrect) with a local 
variable for the result. For each accessible element of an 
opaque data structure there is a corresponding new routine 
for getting or setting that elemenL 

Supporting <)paque TtK>llx>x staictures likely will take some 
work in your code. To begin with, you probably will have to 
create new local variables for return resulLs. Almcxst all accessor 
fundions return a t:opy of the data and not a pointer to the adual 
data. This passing of data by value instead of by reference 
requires that you allocate space for results either in memory t>r as 
local variables on the stack. For efficiency, you should place calls 
to accessors Mraicgically in your code and use them minimally. 

Window records are opaque in Carbon, and are not just 
extended versions of Grafyorts. Window.s and pons are no 
longer synonymous, and ctxle that Lreais them interchangeably 
will crash on Mac OS X. For example, the following statement 
casts a WindowPtf to a GrafPtr: 

SetPort( (GrafPtr) aiyWindow ); //don'ido ihis! 

look familiar? Code like this will cause you grief in the 
future because your program will compile and run just fine on 
Mac OS 8 but crash on Mac OS X. Tlie right way to get the pon 
for a window is with the GetWindowPort function, like this: 

SetPort( GetWlndovPort( ciyWindow ));//do ihismstc-ad 

Another practice to avoid is hanging your own data off the 
end of Toollxjx stRictures. For example, because the inicrnal 
representation of a w^indt jw record is no longer visible, you cant 
save private data by adding it to tlte end of the window record 
and passing a pStorage value to NewWindow. In Carbon, you 
must pass NULL in the pStorage field. If you need extra storage 
for windows, keep a reference to your data in ffie refCon field. 
If you are currently using pStorage in this way, switching to 
refCon is something y ou can do today to pmpare for Carlxjn._ 

The upside to iliese changes ih llial Apple can take steps to 
ensure that the internal representation of data is aligned in 


memory for fastest access, and new elements can be added for 
Carbon-specific feaaires. With opaque data structures in (Carbon, 
the Ttx>Ibox easily can f>e extended in the future. 

Not all data struaures are opaque in Carbon, though. 
TextEdit data in a TERecord, for example, still is directly 
accessible. The Apple Event AEDesc structure also is direedy 
accessible, but tlie type of the data Handle in the stRictore is 
opaque. Some data smtoures were not made opatjue t)ecause 
they're so simple, like the AEDesc structure, and others because 
the Ttjolbox component is not expected to change in the future. 
This is why tlie TERecord is not opaque, as TextEdit will be 
replaced outright by a Unicode aware text engine. 

VH. Adopt Supported Technologies 

A number of Mac OS functions are n<)t being carried 
forward in Carbon. For these you must adopt Apple's 
suggc.sicd replacement functions or find other way-s of 
accomplishing those functions. Carbon is a work in progress, 
and you may Rin acrass a few^ APIs that are listed as 
unsupported in Carbon but for which replacement APIs or 
workarounds are not yet defined. If you feel strongly that 
Apple should suppoR an API that is listed as unsupported or 
under evaluation in the Carbon Specification, make your voice 
heard by sending e-rnail to <carbon@apple.COm>. 

Three important Carbon-supported leefinolugies that you 
should adopt totiay are the Appearance Manager, Navigation 
Services, and Open Transport. The Appearance Manager 
coordinates the look and feel of the Mac OS human interface 
and provides a rational and .supported API for adding custom 
interface elements. 

NavigiUion Services replaces the venerable Standard File 
Package, :md is shipping now in Mac OS 8.5. Using sample axJe 
providexi tn the Navigation Sendees SDK Cavailalrle on Apple’s web 
sire), we were alile lo replace all ilie Standard File calls in 
Ap[^JeWorks in one day. You also should read Keith Mortensen's 
excellent article on the subject in the August 1998 Ls.sue of MacTech. 

Open Transport replaces MacTCP and classic AppleTalk in 
Carffim. If you liave not already adopted OT, now is definitely 
the time. First introduced in System 7.5.2, Open Transport has 
evolved into a mature, efficient, and extensible networking 
architecture capalde of saturating lOUMhit Ethernet, 

Vin. DonT Patch Traps 

You cannot patcii traps in Mac OS X for one simple 
rea.s<m: iliere is no trap table. Because the operating system 
is PowerPC native, no 68K trap table ts needed. Unlike Mac 
OS 8, most calls to Mac O-S X Toolbox functions are 
implemented as a jump directly to the specified routine. In 
Mac OS 8 you can patch traps to intercept T'oolbox calls and 
modify their behavior, but with no central dispatch 
mechanism to hmk into, this is not possible in Mac OS X. 

Consequeniiy, GelirapAddress, SetlrapAddress, and 
related functions are not available in Carbon. You can, of 
course, conditionalize your code and continue to patch traps 
when nmning under Mac OS 8, l)ul your programs will be 
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much easier to maintain if you avoid patching entirely. 

Apple is considering a variety of mechanisms to allow 
programmatic extensibility, 'fhe goal is to provide you with 
system-level APIs for altering certain default behaviors. If you 
have suggestions or specific re<|uircments that you would like 
Apple to support, send them to <carbon@apple.com>. 

For now you should take a close look at any trap patches 
in your crxle and ask yourself if they could ixr replaced wilii 
another approach. Instead of patching ExitToShelf, for example, 
try using a CFM tennination proc for your main fragment. 

IX* Draw Only Within Your Own Windows 

Because Mac 05 X is a truly preemptive system^ any 
number of applications may be drawing into their windows 
at rhe same lime. And of course, a user may be dragging a 
window or other object around the screen while background 
applications are drawing in their windows. In f>rder to make 
all this work, Carbon applications must play by these rules: 

First, you sliould no lunger try to draw outside of your 
windows. In the past you could call the GetWMgrPort 
function and use that port to draw anywhere on die screen. 
This port no longer exists in Mac 05 X, If you were using this 
technique for custom dragging or zooming feedback, use 
Drag Window or other Drag Manager functions instead. 

Second, if you draw directly into the bitmap of your 
windows (without using QuickDraw) you must wrap those blits 
with two new calls tliat will tell the Window Manager to get out 
of the way. We are still working on these functions, stj for now 
you miglu just want to insert some comments to remind you that 
you eventually must update this kind of code for Carbon. 

X* Manage Memory Efficiently 

Memory management does not change much for Carbon 
applications running on Mac OS 8. You will need all die code 
you lise Kxky lo manage heap fmgmentation, low memory 
situadons, and stack depdi. 

However, there are some things you must do to perform 
well when running in a Mac OS X enviromnent. In that 
world, your application will am in a veiy difterenr heap 
structure with different allocation behavior. Your memory 
will not tend to move as much and your slack will be far 
away from ytmr heap, witli guard pages below it. The most 
significant change you must make is in determining amounts 
of free memory and stack space available. 

In the future, when your Carbon application is intended 
to run only on Mac OS X, you will be able to take full 
advantage of new memory behavior. You might switch from 
handle-based to pointer-based alkK'ations, for example. But 
as long as your application runs on Mac OS 8, you should 
prepare for the same issues you always have. 

The functions Free Mem, Purge Mem, MaxMem, and 
StackSpace are all available in Carbon. You should, however, 
think about how and why you are using them. You will 


probably want to consider additional code to better tune 
your performance. 

The FreeMem, PurgeMem, and MaxMem functions behave 
as expected when your Carbon application is ninning on Mac 
OS 8, but they are almost meaningless when it is running on 
Mac OS X, where you have essentially unlimited virtual 
memory. Although you can still use these calls to ensure that 
your memory allocations will not fail, you should not use 
them to allocate all available memory. Allocating too much 
virtual memory will cause excessive page faults and reduce 
system performance. Instead, determine how much memory 
you really need for your data, and allocate that amount, 

Bcdorc Carl)on you would use the StackSpace function to 
determine how much space was left before rhe stack collided 
with the heap. Ihis routine c'ould not lx: called at mtermpt 
time, but was useful for preventing heap corruption in code 
using recursion or deep call chains. But, since a Carbon 
application may have different stack sizes under Mac OS 8 and 
Mac OS X, the StackSpace fund it )n Ls no longer very useful. 
You slu)uld not rely on it for your logic to terminate a recursive 
function. It might still l^e useful as a safety check to prevent 
heap corruption, but for terminating runaway recursion you 
should consider passing a counter or the address of a stack 
local variable instead of calling StackSpace. 

The Carbon API does not include any vSubzone creation 
or manipulation routines. If you use subzones today to track 
Toolbox or plug-in memory allocations, you will have to use 
a different mechanism. For plug-ins, you might swiicli to 
using your own allocator routines. To prevent leaks of 
TooIIk>x data, make sure all Toolbox allocations are matched 
with the appropriate dispose calls. 

'l‘he Carbon API also removes the definition of zone 
headers. You no longer can modify the variables in a zone 
header to change the behavior of Toolbox routines like 
MoreMasters. Simply call MoreMasters multiple times instead, 
w'hich will allocate 128 master pointers each time. 

Summary 

Hveryihing you do now to make your application run 
great on Mac OS 8 is a step coward Carbon compatibility. 
Adopting the Appearance Manager, Navigation Services, and 
Open Transport is a great way to .start. And l^y following the 
steps iiuLlined in this article, your transition to Carbon will be 
that much easier. 

While it has been our experience that a typical application 
can be Carbonized” in a c{>upie of weeks, a lot depends on 
how zealously you have followed Apple’s programming 
recommendations in the past. If you have not cracked a copy 
of Inside Macintash in a couple of years, or do not remember 
the last time you synchronized with Apple’s latest header 
release, it might take you a bit longer to whip your code into 
shape. All the more reason to get started early! Ki 
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By Miro Jurisic 

Calling CFM Shared Libraries 
From Classic 68K Code 


Things they don't tell you 


generating CFM glue code automatically from a Perl scripL 


in Technote 1077 . ■ ^ r , , ^ 

This article aiisiimes thac you are familbr with the Code 
Fmgment Manager and shared libraries (as dcserilxjd in 
Introduction 11M:PPCJ and lIM:RTAl), and that you have read TN 1077 

One of the great things ab(3uL fTN1077l 
Macintosh software Ls that older 68K 


applioiion software tends to work on CoRRECrLY wmi System 7 

tlie newer PowerPC machines and that lire code in TN 1077 does an incorrect check to 


user of the older machines can get 
modern software. One example of tliis 
is Apple's siippc^rt for the Code 
Fragment Manager on 68K 
C‘C1'M68K'') l>egiiining with System 
7.1. With this, 68K code can use the 
Code Fragment Manager to implement 
libraries and plug-ins, or can call 
PowerPC code when running 
emulated on a PowerPC system. 

Geoige Wagner Rrst described how 
to c'till CFM shared libraries (wfieiber 
PowerPC or ()8K) from 68K code; you can 
find this as Apple Developer 'technical 
Suiipott Tccimoie 1077 (TN 1077). 

'Phis anicle contains improvements 
to the code provided in TN1077, 
making the code mt>re ixihiust and 
provides examples of additional 
problems and techniques. In particular, 
ibis anicle describes: 


determine ilie runtime architecture of the machine it's 
running on. 

The problem with the TN 1077 code is that it returns 
an error when the gestaltSystemArchitecture Gestalt 
selector is not installed, i.e., on all versions of Mac OS 
before 7.L2. However, CFM-68K is l>ackwards ctMnpatible 
to system 7T; as a result, TN 1077 glue code fails to load 
CFM-68K shared libraries on Mac OS 7J and 7.1,1. 

Tlie corrcci version of i he code is: 


G etSystem A rcli itectu re 

CiCtSystemAirhitct^iure determintfs systetti archicecturt^ it isi ninning in 
(6BK or PPG). 

static pascal OSKrr GatSystemArchitecture ( 

OSType *ouCArchType) 

I 

// siatk so wt otdy Cicstiilt once 

static long sSysArchitecture = □: 

OSErr tOSErr = noErr; 

// assume wild ardiitecturc 
“outArchType = kAnyCFragArch: 

// If we dont kmjw die system ardiiteLtiire yet... 

// Ask Gestalt what kind of machine we are running on. 
if (sSysArcbitecture = 0) 

tOSErr *= Gescalt(gestaltSysArcbiieciure, 
fesSysArctilLee tura) ; 


• calling CFM functions that return 
pointers^ 

• calling CFM functions that cannot 
be directly called via the Mixed 
Mode Manager because of their 
prototypes, and 


if CtOSErr = noErr) \ //ifnocmjrs 

if (sSysArcbltaeture = gestaltSSk) //l>8k? 

•outArchTyps ^ kMotorolaOSKCFragAreh: 
else if (sSysArchitenture == gestal tPowerPC) //PPC'? 

^outArchType ^ kPowcrPCCFrugArch; 
else // who knows whiii might be next? 
tOSErr = gestaltUnknownEtr: 

1 else if (tOSErr == gestaltUndefSelectorErr) 1 
// No system strehiteeLnre gcsiiilt 


Miro Jurisic is a wacky Fnropt^an wurking ftir Ma.^.sadlusetls Institiiic of Technology Information .Systems In his free Time, he 
is a ft ill-time siudeni ai MIT, working on hi.s MasttTs degree in Computer Science and Bachelor's degree in Matliematics. His 
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//We must be runutnf' on a system tiJder than 7.1 2^ so 
// we ate on a 68K machine. 

*cjutArchType ^ kMotiorola68KCFragArch: 
tOSErr = noErrj 

1 

return tOSErr; 


Chjecking for CFM-68K 

The TN 1077 code does not check for presence of the 
Code Fragment Manager before calling it to load the library. 
This causes the glue code to crasii 68K machines with an 
Illegal A'Tiap when CFM-68K is not present. To foe this 
enor, we add code to the Find_Symbol function to check for 
presence of CFM: 


FLnd_Symix>l 

Addition to the Find_Symhol hjnecion that correctly checks for presence 

of CFM befoiie calling it. 

static pascal OSErr Find_Symbol ( 

Ptr‘ pS 3 ?i[iA<ldr ♦ 

Str255 pSymName. 

ProcInfoType pProcInfo) 
i 

/• Code to determine the runtime architecttire goes here*/ 
if (SHavcCFMO) t 

// If we don't have CFM68K 
// return a rcasonabk-ltHiking error 
sOSErr - cfragLibConnErr; 
return sOSErr; 

1 

/* Code to load the library and find the sj'mboi g^tes here 7 


Cieady, we also need to add the HaveCFM{) function: 


HavcOM 

Checking for presence of the Code Fragment Manager 
sla Lie pascal Boolean HavcCFHtvold) 

( 

OSErr theError ^ noErr: 

// static wc <miy call Cicstalt once 
static Boolean sHaveCFM = false: 
static Boolean sCalledGestalt = false: 
long response; 

if C1sCalledGestalt) f 

theError Gestalt(gestaltCEHAttr» ^response): 
sCalledGestalt " true: 
sHaveCFM = 

{theError = noErr) && 

{((response gestaltCFMPresent) k 1) E= 0); 

J 

return silaveGFH: 


Prototypf Restrictions 

Restrictions in die Mixed Mode Manager limit which 
functions in a CFM shared library can be accessed from 
classic 68K code. Only functions 

• which have a fixed numl>er of arguments 

• which have no more than 13 arguments 

• whose arguments and the return value (if the function 
returns a non-void value) all have size of h 2, or 4 bytes 
can be called from classic 68K code. 


This means that you cannot access any functions chat 
take or return structs or some floating-point types; 
however, you can use functions timt take or return pointers 
to structs or pointers to floating-point types. 

Thus, if you control the library, you may want to 
consider changing the library interface so that your 
functions satisfy the above conditions. If you do not 
control the library^ or you cannot change the library 
interface, you can write a wrapper library which provides 
an interhice that can be called from classic 68K, and just 
calls the real library to do the work (with arguments 
appropriately rearranged). 

For example, if you have a function in a shared library 
wilti die fcdlowing prototype: 

myFiinction 

Ex^implt: of a fiuicdon ihai caimoi be ealled via ihc Mixed Mode Manager 
struct jnyStruct I 
UTut32 a; 

UInt 32 b: 


//'llie following function can’t be called from classic 68K 
// using Mixed Mode Mamiger because ilie siise of its 
// arguments and the return value is not 1,2, or 4 bytes, 
my St met. myFunctlon (my St met paraml. my Struct 
paraia2) : 

then you can write the wrapper function like this: 

myFnnctionWmpper 

Example of a w rapper function dial am be eallcd via the Mixed Mtxlc 
Manager 

//llie Jxjllowing function can be called from classic 68K 
// code using the Mixed Mode Manager 
// Note how the ’Nvrapper function avoids having to deal 
// widi memory^ iillocaiion by changing the return value 
// into a non-const pointer iit^umcnt 

void myFunctionWrappe]: (myStruct* result, const 
myStruef* parami* const myStruct* param2) 1 
‘result = myFunctlon (*parami, *param2): 

} 

If you put this wrapper function in a shared library, 
then you can call rhe wrapper function from your 68K 
code (because the wrapper function does not violate the 
Mixed Mode Manager restrictions), and the wrapper 
function can call the real function (because that is just a 
cross-fragment call that does not have those restrictions). 

Tl is not possible to write a simple wrapper for a shared 
library function which takes a variable number of 
arguments, such as the C "'prinif' function. First of all, even 
if you could write a wrapjier function, it would still be 
Limited to no more than 13 arguments. However, the real 
problem is that the procedure information you would have 
to pass to the Mixed Mode Manager depends on the 
number and the types of the arguments, and this 
information is lost once the arguments are put on the stack. 
Either you would have to pass tlie number and sizes of 
arguments into tire glue function, or the glue hmetion 
would have to pai-se the arguments to detei'mine how 
many there are and how big they are. 
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We can use prinrf as an example, 
printf ["Hello, my najae is %s\n'\ ‘^Miro") : 

The printf function has to take the first argument and 
use the information provided there to extmct the remaining 
parameters from tlie stack. To write a wrapper for tfiis 
Rinction, you would have to write a parser to extract tlie 
arguments, build the appropriate routine descriptor, and 
push them back onto die slack in the correct form before 
calling the function. 

In any case, the work involved in writing the wrapper 
function is probably belter spent rewriting the library 
function to take a fixed nuinl:ier of arguments. 

Correctly Handung Library Functions 
iiiA'r Return Poinitrs 

Suppose your classic 68K code makes a call into a CFM 
shared libniry via glue code. The call is executed like this: 

• Your classic 68K code calls the classic 68K glue 
function, passing arguments according to a 68K calling 
convention. The particular calling convention used 
depends on the ccj^mpiler options used to compile the 
glue functions. 

• Tlte glue calls the CFM library function using a Universal 
Procedure Pointer (IJPP). 

• The UPP invokes the Mixed Mode Manager, which 
examines the information in the UFP to determine how 
to rearrange the arguments into the CFM calling 
convention. 

• Ihe Mixed Mode Manager calls the Ci'M function. 

• The CFM function executes, taking its arguments 
according to the CFM calling convention (68K or PPG, 
depending on which architecture die code is running 
on). 

• The CFM function places iLs return value in the 
appropriate place, again accc^rding to die CFM calling 
convention. 

• The Mixed Mcjde Manager returns control to the classic 
68K code in die glue function, leaving die return value 
of the CFM function in the DO register. 

• The glue function takes the return value and returns 
it to its caller. 

To find arguments passed by the glue function and 
the value returned to the glue function, the Mixed Mode 
Manager uses procedure information in the UPP. Thi.s 
means that you have to make sure that compiler options 
you are using to compile the glue functions match the 
procedure information in the UPPs for the .shared library 
functions. Otherwise, either your shared library function 
will get garbage arguments, or the glue function will get 
a garbage return value. _ 


If your glue functions follow Pascal calling 
conventions, then you should use kPascalStackBased as 
the calling convention in procedure information. 

If your glue functions follow C calling convention, 
and are compiled with an MPW compiler, or with another 
MPW-t:ompaLible compiler (.such as Metrowerks compiler 
with ‘'MPW Calling Conventions'’ turned on), then you 
should use kCStackBased in procedure information. 

If you are compiling with the default settings for 
Metrowerks compilers, then your glue functions will 
follow the IhinkC calling convention, and you should 
use kThinkCStackBased in the procedure information. 
There is one twist, however: if the return value from a 
UPP call is a pointer, the glue function will expect the 
result to be returned in the AO register instead of the DO 
register. However, the MixedModeManager will always 
put the return value in DO if UPP has 
kThinkCStackBased for its calling convention. 

Therefore, if you stan with the default settings for 
Metrowerks compilers, yOLi have to compile your glue 
functions so that they expect the results to always be 
returned in DO. This is done by surrounding your glue 
code with the folltjwing pragmas: 

#pragma dO„polnLcrs an 
// Prototypes glue functions go licrc 
Ifpragina dO_poiTLtej:s reset 


Generating Glue Code Programatically 

As T was working with CFM glue for .several shared 
libraries, it occurred to me that writing the glue was a 
fairly mechanical process; there is a section of code 
that's invariant, and a secion of code that contains glue 
functions, but the glue functions follow a fairly 
.Straightforward pattern. Thus I thought generating the 
glue with a script might be a good idea. Looking at my 
options, I decided that Perl was a good tool for the job, 
so 1 summoned my local Perl deity. 

She consed up^ a script that takes as input a list of C 
function prototypes, such as: 

Samiplc prutcitype? list 

tflntl6 sampleFunl (vold^ OTnt32 arg2) : 

void sarapleFun2 (UlutSZ* argl♦ UIntl6 arg[]); 
void samplcFun3 (void) ; 

Although it may seem annoying that you need to take 
your existing C headers and strip them down to the form 
accepted by tlie Perl scTipt, we decided tliat it would be 
slighdy impractical to implement enough of a C parser and 
semantic analys^er in Perl to extract prototypes from a 
regular header file. 

The script uses MaePeri and its MPW tool; before you can 
use the ^,pt, you will have to install MacPerl and the tog! 
fsee fMacPeril for download and insmllation instructions). 
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The output of the script for the above input is: 


Sanipk' glue genemteil by Lite script 

/**** samplcFun I “/ 

r UIntl6 sampIcFun 1 (void* argl,Ulnt52 arg2); V 


emm I 

saropIeFunl_PrQcIn±‘^o " kThinkCStaekBased 
HEStILT SlZE(SlZE_CODE{3i2eof(UTntl6))} 
STACK_ROUTINE PARAMETER 11. SIZE^CODE(slzeof(void 


STACK_ROUTINE^FARAHETER(2 * 
SIiE.CODE(3izeo£(UInt32))) 


// if this s>Tnbol has nut been setup yet,.. 
it(tPtr) sampleFunS ProePtr = 

(Ptr) kUnresolvedCFragSymbolAddresii) 
FindLibrarySyinbol ((Ptr &sampiefmi3_ProcPLr, 
"\psainpleFuii3", 
sarnpleFun3_Proclnf o) ; 
if {(PTf) safflpleFun3_FrocPtr !• 

C Pt r) kUn resolvedCFragSyrabolAdd res s) 
sattipleFun3_ProcPi:r{) i 


Once we prcxluce this outpui, we need to assemble it 
into a final glue file t:<)nsisling of: 


typedef UTntl6 (*sampleFunl_ProePtrType)(void *, 
Uiiit3 2) 1 

Hint 16 samplsFiml ( 
void * argl, 

UInt32 arg2) 

I 

static sampieFunl_ProcPt rType sa]iipleFunl_ProcFLr " 
ktln r esol vedCFr agSymbolAdd ross; 

// if this symb<il has ncji been setup yci,., 
it {(PtrJ samplfiFunl ProePtr = (Ftr) 

ktinresol vedCFragSy mho 1 Ad dress) 

FlndLibrarySyrabol (CPtr &sainpleFunl_ProcPLr, 

‘'VpsampleFunl", 
sanipleFunl_Procinf o) : 
if ((Ptr) sanipleFunl_ProcPtr I’- 

(P t r) ktln r esolvedCFragSymboLAdd resn) 
return sampleFiml ProePtr (argl, arg2); 


/**** sampkl'unZ *«7 

/‘ void samplel'uni {lJlnl3Z* argt,lllntl6 argil):*/ 
enmii [ 

sampleFun2_ProcTnfo “ kThinkCStackbascd 
I STACK_ROUTTNE„PARAMETER 11, SIZE_CODE(sizcof (nTnl:32 

I STACKJ10UTIMK_FARAMFpTER( 2. SIZE_C0DEUizeof(lJIntl6 
*))) 

typedef void (•sampleFun2_ProcPtrType) (trTnt32 

UIntl6 *): 

void saiapleFuii2 ( 

UInt32 * atgl. 

UTntl6 * arg) 

I 

static saaipleFnn2_ProcPtrTypG samp! aFunl^ProcPtr “ 
k Un resn1ved CF r a g Symb oiAd dress; 

// a this symbol has not been setup yet,., 
if t(Ptr) sattipleFun2„PtocPtr 

C Ptr) kUnr esolvedCF ragSymbolAddres s) 
FindLibrarySymboK (Ptr *) &sattipleFun2_Proc?tr» 
"\paatrtpIeFun2'*, 
saJiipleFun2 Froclnfo) ; 
if ((Ptr) RampleFuri2_ProcPtr ! = 

(Ptr) kUnresolvedCFragSymbolAddress) 
sampleFun2_ProcFtrCsrgl, arg): 

I 

/•*** sampleFiin3 ****/ 

/* void sampieFun3 (void) */ 

enum I 

sainpieFun3_Prcicrnfo - kThlnkCStackBased 

typedef void (*sampleFuii3„PtocPtrType) (void) * 
void sampieFunB ( 
void) 

i 

static saittpleFun3_ProcPtrType sampieFuii3_ProcPtr " 
kHnresolvedCFragSymholAddress: 


• a preamble, containing a #define for the libraiy fragment 
name, and #includes fi>r all the header files needed by 
the glue hi fictions (which is at least the header files 
containing glue functions* declarations and some system 
headers), followed by 

• the general glue code, containing HasCFM{), 
GetSystemArchileclureO, and RndLibrarySymboi() 
functions, followed by 

• the auto-generated glue functions from alx>ve, followed by 

• a postamble, containing any other code tliat we may 
want (and tliat requires any of the ctxle in the general 
glue); typically, this is a function tliat tests for presence 
of the sharetl library. 

We generate the final glue file with the following 

MPW commands: 

perl MakeCFMOlue.pl < :Q1ucExample.proto.h > d 
I GlueExampie.Clue.c 

Catenate ;GlueExample.Glue.pre.c :Glue.C 8 

;GlueExample.Glue.c ;ClueExample,Glue,post,c I d 
Catenate > iGlueExample.Glue.c 


Gotchas 

As nt)ted tefore, the Perl script is nowliere near as smart 
as a C compiler. Becavese of this, the script cannot detect 
some things that you cannot or should not put in your glue 
code, such as: 

• functions whose arguments or the return value have 
size other than 1, 2, or 4 bytes; 

• ftinaions that take arguments or return values whose size, 
wlicn passed or returned, is I, 2, or 4 bytes, but whose 
sizeofO is not. 

The script also does not detect the following 
conditions which will generate incorrect glue code: 

• functions whose prototypes are not legal C 

• functions whose prototypes contain C preprr>cessor 
macros 

The script will detect the following problems in 
your prototypes: 
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• functions with no arguments and no dummy void 
argument 

• functions with a variable argument list (either ... or 
va^list) 

You should l>e especially careful about types whose 
sjzeof()is not the same as their size when passed as 
argument; this is somewhat tricky, as it is usually not 
obvious. Consider the following code: 

typedef UTni:32 TwoWordType |.2J : 
void myFunction (TwoWordType arg): 

Script-generated glue for such a function would 
contain the following procedure information; 

eniira f 

myFuiictiori_ProcIiifo "" kThinkCStackBased 
I STACK_ROUTINE_PARAMETER(1. 

SIZE CODEtsi^eof{TwoWordType})} 

M 

Ihe problem is tliat sizeofOwoWordType) is 8, but a 
TwoWordType is passed on the slack as a pointer. So, the size 
that we really want to use here is tlial of a Uint32D. Using 
sizeof (TwoWordType} causes the procedure informal ion to 
indicate the size is 0 (see the definition for SIZE_CODE in 
MixedMcxle.h), i.e., no argument is passed, so that the CFM 
library function gets gar!:)age in. (“Nasty.’' “Yeah,") 

A cypedef to an array type ts the only case that we 
could find where a bizarre thing like this happens, l>ut 
it U)ok us a while to figure it out, so he careful with 
your typedefs when CFM glue is in town, 

Ihese weaknesses of the Perl script are the main 
reason why we consider it a feature that you need to create 
the pmtotype list (mostly) by hand, l>ecause you have an 
opportunity to JtK>k at all the prototypes at that lime and 
inspect them for possible problems, 

A Complete Example 

Complete source for CFM glue functions is provided 
with the article; the code consists of the following: 

• GlueExample library: a sample CFM library (includes 
functions that cannot Ix^ called from classic 6HK wiUiout 
a wiapper). 

• GtueExamplc.h: header file containing function 
declarations for the shared library. 

• GlueExamplex: shared library source. 

• GlueExample.mcpi CodeWarrior Pro 2 project for the 
shared library, 

• GlueExample.Glue.c: source file containing glue code 
for GlueExample library. 

• GliieTest test application: sample application that uses 
GlueExample glue. 

• GlueTest.c: the application source. 

•^GlueTest.mcp: CodeWarrior Pro 2 project for the 

application. 


• WrapperExample library: a sample CFM shared library 
which provides wrappers for functions in GlueExample 
that cannot be called from classic 68K code. 

• WrapperExample.h: wrapper function prototypes, 

• WrapperExample.c: wrapper function implementations. 

• WrapperExamplcMncp: CtxleWarrior Pro 2 project for 
the wrapper libraiy. 

• WrapperExample.Glue.c: source file containing glue 
code for the WrapperExample library 

• WrapperTest test application: an application that calls 
functions in GlueExample that cannot be called directly 
via the Mixed Mode Manager, using WrapperExample 
library. 

• WrapperTest.c: application source. 

• WrapperTest.mep: CodeWarrior Pro 2 project for the 
application. 

• GlueExample and WrapperExample glue 
autugeneration: sources and script that autogenerate 
GlueExample glue. 

• Gluex; the invariant portion of CFM glue. 

• GlueExample.Glue.mpw: MPW script with commands 
iliat generate GlueExample glue 

• GlueExample.Glue.pre.c: preamble for GlueExample 
glue autogeneralion. 

• GiueExample.Glue.post.c: postamble for GlueExample 
glue autogeneration, 

• GlueExample. proto, h: prototype list for the 
GlueExample libmry, input to the glue generation script. 

• WrapperExample.Glue.mpw: MPW script with 
commands that generate glue for WrapperExample 

• WrapperExample.Glue, pre.c: preamble for 

WrapperExample glue autogeneration. 

• WrapperExample.Glue,posLC: postamble for 

WrapperExample glue autogeneration, 

• WrapperExample. prokxh: prototype list for die 
WrapperExample library, input to the glue generation 
script, 

• MakeCFMGluc.pl: Perl glue generation script. 

• CFM,init'rerm,h: declarations for standard Metrowerks 

_initialize and_^terminate routines, called from Glue 

library initialization and termination routines. 

CONCIXTSION AWD DEBlJCKilNG TmS 
Writing classic 68K glue for CFM library functions can 
be tricky. There are plenty of ways to make a mistake, and 
most of them result In moderately baffling failures. Here are 
some things to try when your glue code doesn't work: 

Check whether your library is getting loaded at all, by 
either: 

• stepping through the code that loads the library and 
inspecting the return value from GetSharedLibraryO or 

• stepping over the code ihiii loads the lib rar y and using 
the MacsBug 'frags' demd to see if the library has been 
loaded. 
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Tf the library' is not getting loaded, make sure that: 

• CFM is installed (either step through HaveCFM(), or 
look at the 'cfrg' Gestalt selector in MacsBug); 

• your library is in the CFM search path (appiication 
file, application folder, Extensions folder). See 
flM:RTAl for details on the search order for CFM 
fragments; 

• the fragment name in the glue code is correct (you 
can see the names of the fragments in a shared 
library by opening it in ResEdit or Resorcerer and 
looking at the ‘efrg’ 0 resource); 

• there is enough room in the heap to load the 
fragment; 

• all Lite fragments your library depends on are available 
(if the error returned by GetSharedLJbrary{) contains 
fragment name other than ytmr li[>rary’s fragment name, 
then that fragment is unavailable and caused your 
library to fail to load); 

If the library is getting kraded, but it is misbehaving: 

• If you seem to be calling a function other than the 
one you expected to call, check that liicrc isn't a 
typo in the glue code for the function you are trying 
to call. Since glue code is a copy-and-paste job, 
forgetting to change variable or symbol names is not 
uncommon. 

• If you seem to be calling the right shared library 
function, but its arguments are garbage (it is very 
helpful at this point if you have I he SYM file for the 
library), there is probably an error in the procedure 
infonnation for that function 

• If the shared library function arguments are correct, 
and the function executes fine, but returns garbage, 
then most likely either procedure information for the 
function is wrong or the glue function was not 
compiled with “pointers in calling convention 
when it should l>c\ 

If all of this fails, then I sincerely hope you are on 
friendly terms with MacsBug... 
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PROGRAMMER'S 

CHALLENGE 


by Bob Boonstra, Wesiford, MA 


TiiRRAiiN Traversal 

You're on foot with cargo to deliver, and a mount^iin range 
Ijctween you and your de.stination. You have no map, nothing 
except a set of elevation readings pnivided by a meticulous 
surveyor that you met at a pub in the last town. And oh, how you 
hate to climb. Fortunately^ this month's Challenge comes to the 
rescue once again with an efficient and lalx^r saving solution to 
your problem. 

The prototype for the code you should write to solve lliLs 
Cliallenge is: 

#ir defined{_cpluapius) 

extern “C*' ( 
ifendif 

typedef long PointNuai, TrlangleNum: 

typedef struct Pnlnt2D I 

double X j r !t coordinate V 

double y; T y coordinate 7 

I Polnt2Di 

typedef struct PointID I 

PolntNum thcPo lntHura: /* point number 7 
Po i n L 2 D t he P oln t; /* x and y coordinates 7 

double ht: /" ixjim Jieigin coordinate) 7 

I PointlD; 

typedef struct Triangle I 

TrlangleNim theTriangleNum; /* triangk mimbcr 7 
Pol n tlfijBi t he Po I n t s [ 11; f* numbers of points eompristng iriangk: V 

I Triangle: 

typedef struct Segiaent \ 

TrlangleHum theTriangleMum: /* bqpnent is port of triangle with this number 7 
PoInt 2D startingPolnt: /* x,y coordinates of segment start 7 

Pol nt 2 D end in gPol n t; t x,y coopdinaies of segment ctMl 7 

) Segment: 

long rnumTrianglcs*/ lnltTerrainHap( 

const PolntiD thePointsl], /* input points 7 

long nmaPoints. /* number of input points 7 

Triangle theiriangles!] /* outputtrianglcNconstructed fnim thePoints 7 

): 

long rnumSegntentsV FlndAPathf 

const Pol n 13D thePo int s []. /* input points (input to InitTcrnunMap) 7 

1 ong numPoints , /* number of input points 7 

const Triangle theTriangles(J, T input triangles (from [nitTenainMap)7 

1 ong nuntT r iang 1 e s. r number of input triangles V 

const Point2D pathStart, T input starting point xj 7 

const Polnt2D pathEnd, T input ending point x,y 7 

Segment theScgmenis [] /* output segments from pathSian to patJiiind 7 


void To rmTe r r ainMap(void): 

Jif defined{_cplusplus) 

I 

Sendif 

Your InitTerrainM^ ro utine is provid ed a set of points 
(thePoints), numlicrcd Ix^tween 1 and numPuints, that define the 
terrain to be traversed. It is required to divide the terrain into a 


set of non-twerlapping triangles (thelriangles) that will l^e 
provided to FindAPath and return the numljcr of triangles created, 
tnitlerrainMap can divide the terrain into any set of triangles, 
provided that each of thePoints is a member of at least one 
triangle, and that none of thePoints is stritlly inside of any triangle, 
measured in the x-y plane, Tlius, given points (0,1), (t ,-1)4-1,1), 
and (0,0), the crlan^e formed by (0,1),(1,-1). and (0,0) would be 
legal, l)uL the triangle formed by (0.1), (1,-1), and (-1 ,-1) would not 
lie allowed, Imause (0,0) Ls strictly inside the latleL 

After InitTerrainMap is called, FindAPath will be called an 
average of 5 times to generate a sequence of theSegments that 
traverse a route from pathStart to pathEnd. FindAPath is provided 
the same set of thePoints given to InitTerrainMap, as well as 
thelriangles produced by InitTerrainMap. Each segment created 
by FindAPath crosses from a poinf along one edge of a triangle 
to another point along an edge of ihe same iriangle. The 
startingPoint and endingPoint of each segment must be inside or 
on the boundary of the same triangle (theTriangleNum). Ihe 
StartingPoint of scgmenl 0 must be pathStart, the endingPoint of 
segment j must be identical to the startingPoint of segment j+1, 
and the endingPoint of the last segment must be pathEnd. The 
starling and ending pcnnis pathStart and pathEnd will be in the 
set of diePoints given to InitTerrainMap, and therefore will be 
vertices in at least one of theTriangles. 

After traversal of some number of paths across the 
terrain. TermTerrainMap will be called, where you should 
dispose of any dynamically allocated storage. 

Unfortunately, the surveyor who provided us with 
thePoints in our terrain map was not considerate enough to 
pul them on a regular x-y grid. However, he was limited in 
the amount of storage he had with him on his mapping 
expedition, so we know that there will be no more than 32K 
points in any given terrain map. 

The Winner will be the solution that minimizes the 
amount of work required to reach the destination, where 
work is a combination of distance traveled and elevation 
change. Specifically, the total work is the sum of the work 
expended on each segment, which is calculated as the 
distance traveled in the x-y plane, plus ten times the absolute 
value of the elevation change from the starting and ending 
points of the segment. In addition, there will be a penalty^ of 
10% for each second of execution time required to compute 
a solution. There is no storage constraint for this Challenge, 
except th at your solu tion must run on a 128MB machine. 
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This will be a naUve PowerPC Challenge, using the blest 
Code Warrior environmenl. Solutions may be coded in C, 
C++, or Pascal 


Tiirle Months Ago Winner 

The December Word Neighbors Challenge was intended 
to be a little easier than some recent Challenges, but 
apparently that was not the case. The Challenge was to find 
all ocxurrcnces of a set of words that occurred within a 
specified distance of one another in a body of text. The 
problem had enough subtle complications that none of the 
four solutions submitted by the deadline complcicd all of my 
lest cases correctly. The solution by Randy Boring, however, 
performed correaly with a twodine code change. It also was 
the most efficieni submission and exhibits some interesting 
techniques, so I chose to publish that solution. The code 
change, while small, was algonthmically significant, so no 
prizes or pchnis are going to be awarded for this Challenge. 
Ludrwic Nicollc and Gregory Sadetsky did submit a correct 
solution, but it was submitted after the deadline. Since they 
described the code as the “ugliest 1 have ever written in my 
entire life”, I decided against publishing that s(j 1 uiion. 

The problem complication ihat tripped up two of the 
solutions had to do with treaunent of overlapping matches. 
‘Ihe problem requirement was to find all occufrenccs of the 
search words in the text where the distance between search 
words is less than a specified amount. No word in the text 
was allowed to l^e part of more than one match, and tlie 
solutions were required to return the location of the first 
matching word. The fact that search words need not he 
immediately adjacent allows tire match sequences to overlap. 
As an example, if the problem is to find a case insensitive 
and order independent match of the words V, ''b”, “c"', “d", 
“e”, and T within a distance of 4 or fewer intervening words 
in the following text: 


c;,2,D,4.b,B,7.B.a.B,D,d,C. 14.B.&.f.F.F.A.b.F.a.c*K.d 


the correct solution is to return the matches starting at 
cliaracter 0 and charaaer 4, as indicated below: 

text: 

c,2.D,4,b*R,7.B.fl.B,D.d,C.U,B,e.f .F.F.A.b,F,a,C.S.d 

matchl: C“--a—d-e^f 

match!: D-B——-F—A'- -E 

Because of the correctness issues, I did not run the full 
set of evaluation test cases that 1 had originally planned. In 
putting together a collection of digitized text to use for 
testing, 1 found my way to the Project Gutenberg site at 
<http://saIlorgutenberg,org/gutenberg/>, home to a large and 
growing collection of digitized literature. It has been quite a 
while since 1 read “Twenty Thousand Leagues Under The 
Sea"", and it wa,s something of a surprise to rediscover, 
cxmrtesy of this Challenge, the fact that Captain Nemo 
doesnT appear until the second half of the book. 


Kandy's solution is sparsely commented, but there are 
some interesting features to notice. Noticing that the problem 
sLalemenl called for numerous searches for each set of text, 
Randy parses the text in liis InitText routine, creating a 
UniqueSummary table of each unique word in the text, and a 
Word Instance table entry for eaefi word occurrence in the 
text. To save space, Randy kept pointers back to the text only 
in the UniqueSummary table, not in the Wordlnslance table, 
which cost him the Challenge win. The problem has been 
corrected in the published solution by adding a word pointer 
to the Wordlnslance tal)lc, increasing storage requirements, in 
order m provide the required nutpui. To make word 
coiTiparisons efficient, Randy hashes each word in the Hash 
function, and uses that hash to compare words in the 
FindUniqueWord function. 

In .searching for a match, Randy divides the code into 
four cases, based on whether the search is case sensitive or 
not, and on whether the order of the search words is to be 
preserved or not. The solution then performs a recursive 
search of the word instance Lalde to determine if a match 
exists within the specified distance. 


r 
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The table below lists^ for each of the solutions 
submitted, the total execution time, the types of errors that 
turned up in the evaluation, the code and data size, and the 
programming language. As usual, the number in parentheses 
after the entrant's name is the total number of Challenge 
points earned in all Challenges prior to this one. 


#1nc1u de <Ma cTyp es-h> 

Jf'include “Nearby ►b" 

#dc^e SINGLEWORDAII.OWED 0 // can't fiiKl a _nearby single word! 
^define DEBUG 0 
#if DEBUG 

^include <lostreani> 
using namespace std; 
tfejidif 


Name 

Tunc 

Memory 

Emirs 

C'/xIe 

Data 

Lang 


(msec) 

Alloc. 


Siic 

Size 


Eaody Boring (83) 

262 

Original* 

B 

7068 

34132 

C++ 

Ed Agolf 

334 

Original 

A 

3212 

4236 

C++ 

Emsi Municr (430) 

2022 

New 

A 

11432 

1624 

C++ 

Ludovlc Nicoile C4€) / 

Gregory Sadetsky (2) 

120964 


tatc 

9676 

434 

c 


- 

New 

CRASH 

5176 

539 

C++ 

A ' problems widi overlapping matches 





B ■ incorrecT reium values before conecLlon; correction required revised memory allocaLiun 


Top Contestants 

Listed here are die Top Contestants for the Programmer’s 
Challenge, including everyone who has accumulated 20 or more 
points during the past two years. The numbers below mciude 
points awarded over the 24 most recent contests, including 
points earned by this monllVs entrants. 


Rank 

Name Points 

Rank Name 

Points 

1. 

Munter, Ernst 

204 

9.Murphy, ACC 

34 

2. 

Saxton, Trim 

79 

lO.Lewis^ Peter 

31 

3. 

Boring, Randy 

56 

11. Nicoile, Ludovic 

27 

4, 

Mallett, Jeff 

50 

12.Brown, Pat 

20 

5, 

Kieken, Willeke 

47 

13*Day, Mark 

20 

6. 

Maurer, Sebastian 

40 

14.Higgins, Charles 

20 

7. 

Heiihcock, JG 

37 

IS-Hostetter, Mat 

20 

8 . 

Cooper, Greg 

34 




There are three ways to earn [:x)inLsr (1) scoring in the top 
5 of any Cliallenge, (2) being die first person to find a bug in a 
published winning solution or, (3) being the first person to 
suggest a Challenge that 1 use. Tiie points you enn win are: 


Wordlnsmntc 

typsdef struct Wordlaet^nce i 

unsigned long mark: 1: //has htxn used in a found sei 

unsigned long usi: 18; // Index of our unique summary 

// a quarter million uniqvjc words should be enough 
unsigned long hint: 13 i // partia] summary 
Hf JRB.CORRECTIOK 
char ‘word: 

#endif 

1 Inst, StackElem. * Stack. *^Set: 

^define kHintSi^e 13 //only ihc presence of upper or lower 

^define kKintMask OxlEFF // p umlh Sim aoic are in ttw: hint 
fl^define i!sMarked(w) ((w).inark) 

//define Mark(wp) (wp’>iiiar:k - 1} 

^define UnMarkiwp) (wp'>mrk - 0) 

//define WordsAreExactlyEqual(wt.w2) ((wl).usi ^ Cw2).usi} 


typedaf struct UniqueSuMnary { 
unsigned long unused:1i 

unsigned long lowerNumbers:5: 

unsigned long lowerLetters!26; 

unsigned long unused2:1: 

unsigned long upperNuiibers;5- 

unsigned long upperLettei:fi:26: 

struct UniqueSuatmary'’next! //of same hash 
chat ’word: 

] US, 'HashList; 

//define US Index (y] (gUS - v) 

//define USfromlndexd) (igIJS['(i)]) 

//if !JRB_C0RRECTI0N 


UniqueSummary 


//define TextPosltionfip) (USfronilndex(fip)->usi)‘>word - gText) 
Ifelse 


//define TextPosition(ip) ((ip)->wQrd - gText) 
//endlf 


//define MAXHASH OxDOOOZOOOL // 8K cmries of 4 bytes = 32K 
//define MAXSEARCHWORDS 100 
tfdefine MAXSTACK MAXSEARCHWORDS 


static HashList gHashTable[HAXHASHI; 
static long gTotallnstances: 

static US *gUS. *gUSLaat: 
static Inst *glnstp« ‘gInstpLast: 
static long gUist; 
static char 'gText; 
static long gTextLength; 


1st place..... ..20 points 

2nd place.....,,J0 points 

3rcJ place......,.,.7 points 

4th place... 4 points 

3tli place...2 points 

finding bug... .......2 paints 

suggesting Challenge..2 points 


Here is the corrected version of Randy's Word Neighbors 
solution: 

Nearby.cp 

Copyright © 199B Randy Boring 

// Corrcchons by JRB DLuked bv the icil lowing define 
//define JRB^CORRECTION I 


#de f i n e kX (0x100) // i nput 

//define kD (0x80) //delimiter 

#define kN (0x40) //numeric 

//define kll (0x20) //upper case (or 5-^) 

//define kM (Ox IF) //mask of bU index within category' 

^define NotJ}elimType(typ) (((typ) A (kX | kU)} "=== 0) 

//define NotDeiiBi(c) (((gCharTypc[c]) k (kX I kD)) — 0) 

//define IsDeliitiTypeEtyp) {{(typ) 6i (kX | kD)) != 0) 

//define IsDellmtc) CC (gdiarType[cJ) & (kX [ kD)) != 0) 


gCharTypc 

static /* const V short gCharTypet 
Hi DEBUG 
256 
//else 
123 
#endif 
] = [ 

/* these arcn t legal input ((ixtKMixl F), accept tab, If, cr 7 
“ kX. kX. kX. kX. kX, kX; kX. kX, kXTkETkDT^xTkrHKFxT - 

kX.kX.kX,kX.kX.kX,kX,kX, kX,kX,kX.kX,kX.kX,kX.kX, 
r begin rest of legal Input with 0x20 (space) V 
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kD.kD,kn,kl3,JdJ.kD.liD*kD. kD.kD,kD,kD.]d5,kD.kS.kD* 

0x40 * 0x41 * 0x42 * 0x43,0x44. // ‘lower’ digits 04 

0x60,0x61,0x62.0x63»0x64»// ‘upper’ dij^is 5-9 

kD.kO,kD,kD,kD,kD, 

kB. //45010x40 

0x23. //A=3ctoanris hUnup arc rcnumbercd as most common 

0x2D. //B 01254167 89ABC 

Ox2E* //C 

Ox2F, //D 

0x20, //i:=o 

0x30, //F 

0x31. //G 

0x28. //H=8 

0x26. //[=6 

0x32. //I 

0x33. //K 

0x23. //Up 

0x2A. //M=A 

0x24. //N=4 

0x22. //0^2 

Ox2C. //P=C 

0x34. //Q 

0x25. //R=5 

0x27. //S=7 

0x21. //T=l 

Ox2B. //O^B 

0x35. //V 

0x36. //W 

0x37. //X 

0x38. //Y 

0x39. //Z ASCnOxlA 

kD.kB.kO.kD.kB. 
kO. //A.SO!Ox60 

0x03. // a=3ctoaitris hlmup arc rcnumbercd as most common 

OxOD, //b 01234567 89ABC 

OxOE. //c 

OxOF, //a 

0x00. //c^J 

0x10. //f 

0x11. //g 

0x08, //h^ 

0x06. //i=6 

0x12. //] 

0x13. //k 
0x09. //l^ 

OxOA. //n!=A 
0x04, //n=4 
0x02. // 0=2 
OxOC. //p=C 
0x14. // q 
0x05. //rr5 

0x07. //s^7 

0x01. //l^l 

OxOB. //u=B 
0x15, //V 

0x16. //w 

0x17. //X 

0x18. //y 

0x19. //t AM3I0X7A 

kD. k 0. kD. kD. // ASTlJ Ox7F Is last legal del i miter 
kX //ASOtOxTF 
#if OKBUG 

r these arcn'l legal inpul! 0x80 0x14- V 
kX.kX.kX.kX.kK.kk.kX.kX, kX.kX.kX,kX.kX,kX.kX.kX. 
kX.kX.kX.kX.kX.kX.kX.kX. kX.kX.kX.kX.kX.kX.kX.kX 
kX.kX.kX.kX.kX.kX.kX.kX. kX.kX.kX.kX.kX.kX.kX.kX, 
kX.kX,kX.kX.kX.kX.kX.kX. kX.kX.kX.kX.kX.kX.kX.kX, 
kX.kX.kX.kX.kX.kX.kX,kX, kX.kX.kX.kX.kX.kX.kX.kX, 
kX.kX.kX.kX.kX.kX.kX.kX. kX.kX.kX.kX.kX.kX.kX.kX 
kX.kX.kX.kX.kX.kX.kX.kX. kX.kX.kX.kX.kX,kX.kX.kX 
kX.kX.kX.kX.kX.kX.kX.kX. kX.kX,kX.kX.kX,kX.kX,kX 
tfendif 
1 : 

static StackEleai gStack [HAXSTACK]: 


tfif BFBBG 

Static long gUniqueHflshEntriest 


static bn altcadyABocated = true; 
ffendif 

static void 

FreeStackfStack *ioStack) 

I 

#lf DEBUG 

'ioStack ^ nil; 
aireadyAliocated * false: 

#eise 

^praema unused [ioStack) 

#endif 

j 

//-//--//—- //— -//--//- 

static Stack 
NewStack(void) 

I 

?lf DEBUG 

if (alreadyAllocated) 

OehugStr("\p already allocatedr); 
else 

a IreadyAl located ■ true: 

#endif 

return gStack: //only wofks once, of course 

1 

//-//- If - -//—//——//- 

static void 
InitStack(void) 

I 

ilflf DEBUG 

alreadyAllocated false: 
tfendif 
1 

-— // - // - // - //- 

static f inline 7 void 

StackPnfib(Stack ‘ioStack. StackElem e) 

t 

#if BEEDG 

if (CMoSUtk - gStack) >“ HAXSTACK) 
DebiigStr("\p blew stack up!*}: 
else 
i^endif 

// •ioStadf-H-= c; 

’•ioStack = e: 

(*ioStack)++: 

J 

//-//-//-//--//-—//- 

// Return the elouerti at Uie top of the stack and pop it off 
static /* inline V StackElem 
StackPopTop(Stack *ioStack) 

I 

#if DEBUG 

if (^ioStack <= gStack) 

I 

DebugStr(*\p poked bottom of stack!”): 
return **ioStack; //no good choice here 
J 

else 

tfcndif 

return ‘(-'ioStack); 

I 

//--//-//- -ff -/y—//_ 

static r inline 7 int 
Stack!fsEmpty(const Stack inStackJ 

I 

return (inStack ^ gStack): 

J 

//- // - ff --//-//-//- 

static r inline 7 int 
SetTsSiteOne(const Set inSet) 

1 

return (InSet — gStack +1): 

1 


// ensures we intt it at first 
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U -//-//--//- 

jpdefine SetAddCs.w) Sl^ckPushCs,w) 

//- a - II——H - -n -//-- 

static void 

S€tReiiiove{5et ^ioSet* Inet *toReiaove) 

{ 

// rcmtmf top dement, and nvrrwrite toRemovie element 
*toRepiove “ StackPopTnpCi oSet): 


Iksh 

// CiciKrraic a case-lnscEtKltive hash from the daaraeiers of 
// the auU-terminaud string; 

// hi 15 Mim of wfH] • w[il where wpi] ^ I 
// Ji2 b* sljtipk sum of w[i] 

// result puts h2 In upper 6 bits of a 13 hit word 
static lon^ 

HaaliCohar char •^outDelltn) 

I 

lon| hi = 0^ h2 " 0, lastHum ^ 1, thisNiua: 
char cw “ *w: // assumes first char not null 
do I 

if (cw ‘a’) //Ls loweitase 

tbisHum “ cw (*a" 1): 

else If (cw >“ 'A') // is uppercase 
thisNtmi “ cw - f*A' - !)• 
else // Is digit 

thisNunt * cwr 
ew * *++«: //the next char 
hi +* lastilu® * thlsNum: 
h2 +“ thlsNum; 
laslNum * thisNuiu; 

1 while (cw) i 
'outDellia = vi 

return (hi + ih2 « 7)) k OxOOOOlFFF; 

1 

II - ~ll -//- II - 11- -//- 

// Returns whether the hash lalrfe vmry at h h valid 

atatic /* inline V Int 
ValldHaahEntrydong h) 

I 

return (gttashTablefhl nil): 

1 

//-- 11 - II --//- //——II - 

static void 

HaahAddfUS *inUSp. long h) 

( 

If (ValidHashEntcyih)) 

I // apprmi to existing hash table list 
inUSp->ne)(i * gHaahTable [h]; 
gHashTable[h] " itiLfSp: 

] 

else 1 // add pew hash table entr)- 
gHashTable [h] - inUSp; 

#if DEBUG 

gUni q ueHa sMn t r 1 t 

frendif 
I 

I 

static void 
InitHash(void) 

I 

double frO " 0.0. frl ” 0.0* fr2 0.0, fri = 0*0: 
long count » siaeo£(gHashTable) » 5: 
double "p (double *) gHashTable: 

do I 

*p - ftO; 

‘{p f 1) - frl: 

•(p + 2) - fr2; 

*(p + 5) fr3; 

p 4; 

I while (count): 
j^if DEBUG 

gUniqucHashEntries “ 0: 

#endlf 

1 


#if DEBUG 

static void 

FrintHashTa ble(void) 

I 

long i: 

for (i » 0; i < MAXHASH: I++) 

If (ValidHanbKntry{i)) 

( 

cout « “h = “ « i: 

HashList e = gHasblabie[ij: 
long ct = 0: 
do I 

cout « "* ** <i e->word: 
e = n->nnxt; 

-H-ct: 

1 while Ce): 

cout endl * ct “ " ct endl; 
1 
f 

#endif 


// Return tnie if the strings are exactly equal 
//This is like strtmp (ifinuring less or greater) 

// Assumes first char of w is not nuU 
ntatic int 

EqualStrings(char ‘w, ehar ’u) 

EqualStfings 

1 

char cw ” cu ” *ut 

do { 

If (cw 1“ eu) 
return 0: 
cw = *++w; 
cu - 

I while (cw) : 
return 1; 

1 


// Return true if the siriiip are equal, igmuing case 
// Assumes first char of w is not null 
static int 

EqualSt^ings!^CS^cha^ *w, ehar 'u) 

j 

EqoalStringsNCS 

char cw " 'w, cu = *n; 
dol 

if (cw >“ ‘a’) // cw bi luwea-ase 

cw -= ('a' - *A'3: // wppercaM: it 

1 f (cu >= ■ a *) // cu is Inwcftase 

cu = (*a' 'A'): // uppercase it 

if (cw I'' cu) 
tetum 0; 
cw ‘t+w: 
cu ^ 

1 while (cw) ; 
return 1: 

1 


// Record the presence of each kiiKl of alphanuntehc char In 
// the word 

// And poini to the actual word idr final exact ebcck 
static void 

CreateSummary(char 'w, US 'usp) 

1 

CitateSiifiimary 

long lowN = 0, lowL = 0, upN * 0, upL = 0; 

short cwtype: 

char C¥ = 'w: 

cwtype ^ gCharTypelcw] i 

uspOword = w; 

do { 

long presenceRit; 

int isUpper, IsHuiiiher : // bfOTmtilually cxchisive 
cw = *++w: 

presenceBit = 0x0001 « (cwtype k kM) : 
isUpper = cwtype A kU: 
isKuraber = cwtype A kH: 
cwtype = gCharTypefcwl : 
t f (isUpper) // upper ease letter or high numher 
i£ (isKufflber) //nmibcr 



upN presencsBit: 
else 


48 


Programmer’s Chauenge 


MacTecji • March 1999 



















upL |- prei^finceBir; 
else if (isNumber) 

IfivM I* ptcsenceBit: 
else 

lowL 1= presenceBit: 

] while (HotDelitiiType (cwtype)): 

uspOunused - 0: 

usp >upperNiimbets ^ iipN: 

usp'>uppfirl-.etiers ^ upL; 

usp->uniiseil2 ” 0: 

itsp ^IpwerNtinbers " lowiJ ; 

usp >lpwetLetters = lowL: 

usp >next ^ nil; 


HiidUiiiquL'Woixl 

// Rriiim the UniqueWordSummsry for ihc word. w. if any 
static US * 

FindUnlqiicWordtchur 'w, long 'outHash, char '•outDelim) 

1 

unsigned short h = Hash(w, outDeliffi)i 
US "usp *“ gBashTabielh) t 
*outHash - h: 
if tJValidHashEntryfh}} 
return nilj 

while (nsp tRqualSUlngs{w* iisp >word)) 
lisp ” uHp )next: 

rcLurn usp: 


AddWuit] 

// HikI woful w in ijush tabje (or add it Jf unique) and 
// Llujld ituftmee pointer and add it 
// Return per u\ next char after wnrtl emts (its drUiiiitcr) 
static char * //next characicr alrcf word 
AddWord(char *w) 

long h; 

char VafterWord; 

US ‘rheUSp “ FindUniqfjeWord{w* &h, AafterWord); 
if (3 theUSp) // ucw^ unique wotd^ add it 
[ 

theOSp ^ glO^ast: 

-gliSTjtsr; 
lif DKBUC 

If ((i'Lr) theUSp < (Ptr)glnstpLast) 

OebugStrt“\p dictionary ran into the index]**); 

#endil 

CreateSujmnary{w, theUSp): 

HashAddttheUSp* h); 

1 

Inst thelnst; 

tbeTnjir .marlt 0; 

theTnat.usl = USIndex(theUSpJ: 

ihcInsiJiint = (theUSp->upperL€tters | theUSp->lowerietter 0 ) 
b kHintKask; 

#if JRB^COmaiON 
thelnst.word w: 

#endif 

•glnetpLasti + =" theTnst: 
return afterWord; 


TnitText 

// Index each word in the text 
static void 

InitTextCchar “text* long length) 
i 

char *13 top - text + length; 

// skip Illegal and delimiters 
while (Tsl}olitD(*text)) 

++vcxt; 

while (text < atop) 

I 

text AddWord (text); 
while (l3Delim(*text) text < atop) 
iitexf: 

I 


FixTcxiAndCountl nsts 

// Return count of word EnstatHx;^ atid lertgiJi of input text 
// Null icmim^uc cadi woid Instance In the icxt 
// Allowed since Hexf b not ccinsi char' 

// Ucipful itinee it sfm[>lifies all w'ttrd ctKling detection 
static long 

FlxTextAndCoijntTnstsfchat *texl* long “outLength) 
i 

long ct ” Dr 

char “textStart - text; 

// find beginning of first word 
while (IsDeiiiiiC'text)) 
f+text: 
while f*text) 

3 

// find entl of word 
while (NotOeli[ii(*text}) 

-H-text; 

-H-c t; // couu i d le w< >rd 

If (“text = 0) 
break: 

‘text! I ^ 0: y/nulMerminaie the wofti 
// find banning of next wtnti 
while [*texl Isl'eliin( * text) J 
’N'lexL; 

1 

“outLength = text - textStart: 
return ct; 


// - //-// - // -- // - 

// A Set is irnpleniented is a Stack (for now) 

ifdefine FillSci(s.w*nj HilStackBackwardsta*w*n) 

idc f1nc RewSe t C) BewSt ack() 

^define FreeSetCs) FreeStack(s) 


pascal void Initialize( 
char “text, 
long difltance* 
void “privatesLorago* 
long GtoragcBytes 


[nitialbc 

/* Nl Hi. rerminated text to bt^ searched V 
/“ max distance bctwxcii neariiy words V 
/* private storage for your ujic 7 
/“ munlicr of bytes In privaieStorage 7 


luitiinshO ; 
lQitStack(): 

gXotalInstances = FixTextAndCountTnntsCtcxi, bgTcxtLength); 


r from gTotalinstances we can guess what strategy to use 7 

// Tnitinstances {Idt to right fixim beginniug, 
postlncrcraontiiig) 

glnatpLust ^ (Inst *) privateStotage; 
glristp “ gInstpLast; 

// IniitlniqucSummaries (right to Idt Jn^m end, postdecrement \ ng) 

// masking with OxFFFFFFFC gives us -hftyte alignment 
gUS * t(US *) (((unsigned long) privateSlorago + 
SiorageBytes) i OxFFFFFFFC}) 1; 
gllSLast ” gUS; 

Tn TtTcxt(icxt. gTextLeugthJ: 
gTcxi * text; 

gOlst = distance + 1; //distance :Ulowcd is 0 ilirough distance 
#if DEBUG 

If (gTotalInstances != glnstpLast - ginstp) 

DebugStr{*'\p gTotalTnatancnn !* gTnstpT*ast glnstp"); 
PrintHashTableO; 

cout « ’*# of words toLnl In Input text: 

“ C< gTotelInstances << endl; 
cout « ■*# of unique words in Input text: 

" « gUS - gUSLast « endl; 
cout « of hash table entries used: 

“ ** << gUniqueHasbEntr len << 

endi; 

j^endif 


liUhtackikijekw'anls 

static void 

FillStackBadcwards(Stack “ioStack* char ‘words[1* long nutiiWorda) 

I 

for (int i ^ numWords - 1 ; i >" 0 ; -i) 

I 
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long duttflEy; // wt don't ntxd the renimol haidi vuJuc 

char *dunHiiy2^ 

Infjt eleiH: 

US *tfUSp: 

>rtJSp = FindUriiqueWord Cwotilsll] , &dLiiiiinyt ^dummyS); 

llflf DEBUG 

if Cull = wDSp) 
t 

DebngStr{"\p find word not in text!”J: 

continue: 

I 

#cndif 

eleoL.tiiark ” 0; 

elem.usi = lJSlndex:{wlJ$ph 

tlem.hint ^ (wUSp-^upperLetters I wUSp >lowerLetters3 
k fcHintHask; 

StackFushCioStackp eleiti); 

1 

) 


Words Arcr£qua]£xcept<l3M: 

// Return irne tf tin- words are satne except for Cisc 

// 1 . Jiims of Inst will be same if words same 

// 2. sunjnwries will tiave same 1>itfields of char presence 

// but for case (tlR upper :md lower fields before compart-) 

// 3. wonis w-ill be letter-for-letier the same (ignoring ease) 
nratic int 

WordsArcHqualKxeeptCBSofTnat wl, Insi w23 
I 

if (wl.hiijt w2.hinL) 

return 0:// ihey bive differtm common Icrters 
US ‘ul = USftQwindexfiifl .usl], *u2 = USfroiDlridex{w2*usi): 
unsigned long ullettera * ul->lowerLetters I ul- 

/upperLetters: 

unsigned long u21etter9 * u2->iowerLetters I u2- 

aupperLetters: 

if (uJlottors ii2leuers) 
return 0: 

if ((ul->lowecietterB | ul >upperietiersJ 

(u2->iQverLetxers | u2->upperLettGru)) 
return 0; 

if (ul->lotfertluiflb 0 rs !- u2■>lowerNuiibers) 
return Or 

If ti]|->upperNiiBibi!rit !- u2->iipperNumbers) 
return 0; 

return (EqualStringaRCS(ul >ward« u2 >word))j 


RtKffnStiCS 

if Fmd the set element (a seaith w<*nJ modelled as an Inst) 
if that Ki the siimc as inst, case-sensiti\e 
static Inst * 

FiridTriSetCS(Set InSet, Tnnt in«r) 

I 

-inSet; 
do ( 

if |WordsAre£xactiyEqual(*inSet, inst)) 
return inSet; 

\ while (inSet->gStack): 
return nil: 


FindTnSetNO) 

// FimI the set riemcnl (a scaich word iiuxlclied as an last) 
if that h the same as iiisi, ignoring ease 
static Inst * 

FindItiSetKCS(Set InSet, Inst inst) 

I 

-inSet: 
do I 

if (tfordsArcEKncilyEqunUMnSei, lnst.1 |[ 
WordsArcliqunlKKCOpLCase(*inSel, Enst)) 
return iiiSet: 

I while CinSet->gStack): 
return nil: 


FindNcxtlDMatchf 3 

Etstic itit 

FlndNf7Xt.TQWa lchCS( Irisl ^euttlosLp. Stoe l; :>r , \t*ug nwixDii^t ) 


( 

long ciLcrDlKt = pg^Dist: 

Inst w - StackPopTop(&st); 
int atBottom “ StacklsEmpty(st): 

do [ 

Tnet currW = '‘currlnstp: 

If CisHarked(cijrrW)) 
goto nextTnst: 

if (WordsArelxac L lyEqual (currW, w) J // this word matches! 
If {atBottom) 
f if we found a sell 
Kark(currlnstp): 

StackPufib (&st, w): // restore our stack iicra 
return 1: 

I 

else // recurse to sec If we can finish finding a set 
if (FindNGxLlOMatcbCS(currTnatp + 1, st, maxDist)) 
[ // set found hy recursion 
Hark{currlnstp): 

StackPuah {&at, w): // astuir our stack item 
return 1: 

I 

else I // no set found by recursiuti 

StackPnsb (Sat, w); // restore our stack item 
return €: 

1 

nextinst: 

^urrDiet; 

f+currlnstp; 

I while (currDiflt)I 

// rm nuiidiing word ftjund within max dLstance 
S t ackPush (&s r, w): ^/ restore our stack item 
return 0; 


FindlOMatchesCS 

static long 

FindTOMatdiesCS(Stack at, long maxTciFind, long matchPositionsij 3 

lost *eurcImsLp: 

Inat *lastlnstp ™ gltistphast: 

Inst w = StacicPopTop(ist): 
long count = 0; 
fif SINGLEWORDALLOWEE 

int atBottom = StacklsEmpty(at); 

#endIf 

for (currinstp ^ gInsLp; currlnsip < lastltintp: ++cLirrTnstp3 
if (iaHarkedt'currlnsip))//already im'd in a found set 
UnHark(currlnstp): 
else ( 

if (¥ordsAr€ExactlyEqual(*currInstp, w)) 

I 

if if STRGLEHORDALLOWED 

1 f (atBo 11 00 ) //1 Mil)- < me search woni! 

matchPositionslcountt+l = TextPosit ion(currinstp): 
else //reenrse 

fendif 

If (FiiidNextiOHuCchCS(currJtisi.p + 1, sU gOlsl)) 
niatchPosltionEicouiit+-t| = TextFoBitiori(currinstp): 
if (count maxToFind) 
break: 

I 

I 

return count: 

1 


RrMlNotlUMaichNCS 

static int 

FindMextiOHstcliNCSdnst 'currinstp. Stack st, long maxDist) 

I 

long ctirrDist = tnaxDlEt* 
lust w = SLflckPopTop(&si): 

Itit utBottop = StacklsEmpty (si); 

do I 

Inst currW = •currinstp: 

if (1sMarked(cur rW ))_ 

goto nextlrist: 

if (¥ordsAr©Exaci1yKqimlCcurrW, w) || 

WordsAroEqualExcep t Case{CUr rW, w)) 
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// Thb weird matdi(-‘s! 

If taTBrtttom) 
i // WT fcmmi a sell 
hark(currlnsip ): 

StackPush i &st, w): // rcjrtfirc cjur sutic rtfm 

return 1: 

I 

else // rreursif m scf if wf can finish fimling a set 
if (FinfiNexrTn«9trhCS(currInstp + 1, at, PiaxOist)) 
t // set fouml hj^ n-tursiem 
Murk(furrInstp) : 

St ackPush (4st ♦ w): // rcslcirf nur stack item 
return I; 

I 

else i // no Sift found by recursion 

StackPuch (Anr, w); // resrore our snick item 
return 0; 

ncxtlnat: 
curtDlat: 

+->'currlnstp: 

I while (currDistJ: 

// no matfhini; wortl ftmud within max distance 
StackPunh (fcnt, w); // rrstorr oiir stack item 
return; 0: 


FindlOMatchcsNClS 

static long 

FindlOMatchesNCSCStack st, long maxToFind, long 

i»at£hPositlons[l) 

t 

Ini;T •rurrTnntpr 

Tnsti 'losstTnstp = glnstpLast; 

Tn s( w ' RteckPopTop C &at)t 
lung count “ tl; 

#if SINCUWORDALLQWED 

Int atBottom -* StackIsEmpty(st} j 
tfendif 

for [currTnntp gfrinlp; cur tlriBtp < lastlnstp: ++currlnstp) 

If [\ uHjtrkod(*t'IIrf Trmtp))// already lustti in a found set 
tiriMfirkfcur r t iiutp): 
else I 

IE £WordsAreExactiyEqual(*currInstp, w) M 
WordsAreEquaiExceptCa^e £ * cur rXnstp, w)) 

( 

tfif SINGLEWORDALLOWF.D 

if latBortofii) //onlj-one skui H wfird! 

inatehPostT lorn 3 [coiinL++J - Text Position (cur rlnstp) j 
el no If rcciirM* 

/food I f 

if (FlndNextlOHatchNCSCcurrrnstp + 1. st, gDist)) 
iBatchPoaitionE[cqunt-H-| ^ TextPositionCcurrlnstp): 
if (count — maxToFind) 
break: 

I 
I 

return nnunt; 

1 


static long 
FindNearbyInOrder C 
char 'wordsM, 
long numWorda* 

Boolean caReSonsU lve» 
Ion g ma t ch Pos Uion s [ ], 
lung ninxMuLches 


Stack St ^ NewStackO: 
long found * 0: 

FillStackBackwarda Cint, words, niimUords) ; 
if fcaseSensit1ve) 

found - FindlOMaUhesCStat. uiaxMatches, matchPositions); 
el se 

found = FlndiOMutchesNCSCst. aaxHatches. matebPofiitionfi); 
FteeStacklisth 
return found: 


tnmlNn£tAt).\t.mh(lv 

static int 

FindMextAOMatchCSdnm ’currlnsip. Set st. long maxDist) 

f 

long currDist ” maxBist: 

Int stBottom = SetlflSizeOneCet): 

dot 

Inst cucrW = *currlnrrpj 
if £iRMarked£curry)) 
goto nexTlnst: 

Insi ‘savelnstp * i’indlnSetCS(at * cutcW): 
if (savelnstp != nil) //found n mat cl i 
[ 

Inst savelnst - * savelnstp ;//only needed in NCIS 
SetRemove(fist, savelnstp): 
if CatBottom} //list Mrarch w^ord 
I // wc found a set! 

Ma rk(currlnstp) : 

SelAdd {&cit, savelnst): // rcsiurc ourM.t item 
return 1: 

I 

else // TCCunrC [o if wtr can llnisli Undine u set 
if (FindNextAOMatchCSfcurrfnstp I I, at. raoxnint)) 

[ // set found by ftciinsion 
Mark(currInsTp): 

Set Add (&s i , Stive f ns I) : // n'Siorr our set iittn 
rolurn 1 ; 

1 

//else // no set found by reeurskin 
SetAdd(&st. savelnst): 

1 

nextliist: 

-ciirrMst: 

Hcucrlnstp: 

[ while (cUrrDiRt); 

/y no marching woul foimd within max distance 
return 0; 


I 




,1 

^ T It 1 t A w o 1 1 1 c 1 or e n 4 o 1 r T m ^ x r i m \ « 

• ■ tr. • , tt. ^ 4 ii 4 

Got Software? ' 

Need help safeguarding your software? If you're 
developing software, you need your valuable work 
protected with 

copyright and trademark registration. Then, when you are 
ready to sell it, you can protect yourself further with a 
licensing agreement. 

1 am a California Lawyer focusing on Intellectual 
Property^ Corporate, Commercial and Contract Law, as | 
well as Wills & Trusts. | 

TKe Law Office of Bradley IM. Sniderman 

visa C 1 *^ ^ DLsitivcr 

Mns(€T Olid AinciU’un Hxim'Jis 

(310) 553-4054 * brad@sniderman.eom 


Find Nearby I nOrtier 

r return number of matches found V 

r words to find in fexi 7 

/* nnmher of words 7 

/* tRK^ if match is case sensitive 7 

/• position in text of firsl word in match V 

t mux nmnlicr of matches to tcium 7 
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RridAOMatchoCS 

static lung 

FindAOHatchesCSCSet st, long maxToFind* long amtchPosltlonstl) 
f 

long count * 0: 

Inst ‘currlnstps 

Inst MaistTnntp ” gTrintpLant: 

I!if STNflTXWORMIJiJ™) 

Int oLBollom " SclTnSiReOne(st); 

for (currinatp = glnstp; cutrinstp < iantinstp; ++currin.Stp) 
if (isHarkedt 'cutrlnstp))// nircady u^d in a found sci 
UnHark(currInstp ); 

Ise f 

Inst *savelnstp ^ FindInSetCSCst, *currlnstp); 

If (navntnntp ! ” nil) //found a match 

[ 

Inal aavoInsL ^ ‘savolnstp; 

SctKemovcCl^st 4 aavolnstp): 

#if SIKGLEWORDALLOWED 

if {atBottoEt) //only one ^arch word! 

matehPofiitions tcount++J TextPosition(currInstp)i 

else //rceunst 

Jendif 

if fFindNcxtAOHatchCS(corrTnstp + 1 , st* gDist)) 

IliatchPofillions (count++J “ TcxiPosiilonfcurrlnaip) t 
S^tAddt&st* savoltist); 
if (count = maxToFind) 
break: 

I 

I 

return count: 


RndNexiAOMafcliNCS 

static Int 

FindNextAOHatchNCS(Inst *curclnstp» Stack st* 
long mxDist) 

1 

long currOlst “ maxDlst: 

ini atRottom " SetTaS t KeOnefst) ; 

doi 

Inst currW ” *currlnstp; 
if {IsHarked(curtW)) 
goto nextlnst; 

Inst ‘savelnetp = FindlnSetNGSfst. currW); 
if (savelnstp f“ nil) //foumi a match 
i 

Inst BavcTnnt “ *8S¥eTnstp;//fuih'needed in NO 
SeLRGMove(&st* aaveTnstp): 
if (atButtoa) // Iasi search word 
( /f wc found a set! 

MarkCcurrlnstp): 

SetAdd(fiiSt* savelnst): //restore uur .sciitctn 
return 1: 

I 

else // rcconie lo see if we can fimsh finding a set 
if {FindMflxTAOMatchNCS(currTnstp + J* st ♦ maxDlst)) 
i f/ set found by recursion 
M«tk(cucrlnatp); 

SetAdd t&st, savelnst]: //a^tore our set item 
return 1: 

} 

//else // mi set found by Kcursion 
SetAddtist, navelnst); 

I 

rmxtTnnt: 

-cufrDist: 

-H-curclnstp: 

1 while (currDist): 

// no matching word found w iUtiii max distarKe 
return 0; 


[nst 'currTnntp; 

Tnsi ‘lastTnsip ’ gTnsipl^st; 

#lf SIWGLEWORDALLOWED 

int atflottoTH = SetisSiaeOneCstJ ; 

#endif 

for (currlnstp “ ginstp: currlnstp < lastinstp: ++currin£tp) 
if (isMarked (‘ cur r Ins t p)} // aheady used in a found set 
IlnHa rk (currlnstp): 
else ( 

!net *saveTnetp ” FinctTiiSetNCf;(8t, *currlnstp); 
if (savcinstp nil) //found a match 
( 

Inst savelnst = ‘savelnstp: 

SetResnove{&st, savelnstp): 

Hf 3IKGLEWORDALLOWED 

if (atBottoiii) //only one search word! 

isatchPositionsfcount+t] - Textposition(currlnstp); 
else //reeufse 

tfcmlif 

if (FindiiextAOHatcliNCS (currlnslp + 1* st* gDint)) 
matchPositions[count++] = TuxtPcjsitiori (currlnstp) ; 
S etAd d(4st ^ save!ns t): 
if (count ^ asflxToFind) 
break: 

I 
I 

return count: 


static long 
FindHearbyAnyOrder( 
char *vor<isf], 
long miipMords, 

Boolean caseSensitive. 
long matchPositions(J , 
long maxMatches 
) 

I 

Set St = NewSetO; 
long found “ 0 ; 

FlllSctC&st. words, numWordfl): 
if (caseSensiLive) 

found = Fi:idAOKatchesCS{st, maxMatehes, watchPosi tions): 
else 

found ^ FindAOMatchesNCS(st. aLExHatches* matchPusitions): 
FreeSetCfiist): 
return found: 


RndNeaibyAjiyOrder 

/* feiurn numbcT cjf matches found V 

/• words to find in text 7 

r number <d words 7 

/* tnic if match Is case stasitivc 7 

/* position in ictt of first word in match 7 

/* max number of matdics to return 7 


pascal long FindNearbyC 
char 'words[], 
long numWords. 

Boolean caseSensitivt, 
Boolean preserveOrder * 
long inatchPoEitionB fl , 
long maxMatches 
) 


FmdNeafby 

/* nnom number of matches found 7 
r words lo find in text 7 
r notnber of words */ 
r iruc if match is cast scruiittvc 7 
r iruc if wtjrds must he kmnd in order 7 
r ptftition in text of first word in roaich 7 
/•max number of matdics to leiuni 7 


if (preserveOeder) 

return FindNearbyinOrder(words< nuniWorda, casoSonsitive^ 
jnatchPositions, maxMatchesJ: 

else 

return FindNearbyAnyOrder(words, numWords, caaeSenaitlve, 
matchpQsitiona. waxMaiches): 


nralic long 
--FindAtiMetc 
( 

long eoimt ^ 0: 


HndAOMatcbcsNCS 
long -natchFoaiiions IJ J 
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COniFER^IUCE 

REPORT 


By Michael Kill man, VPN Guru 


Macworld San Francisco, 1999 


Expo Developer 
Tools Roundup 


The cm ire com purer industry 
depends on developer tools. Wiilumt 
developer tools, there's no software, and 
wiilumt software, ii dtKtsn’t matter as 
much what color your iMac 
is >). *rhe tools market is also a reliable 
indicator of where the industry is 
headed. When interest in developer 
tools is h\^\\ more programmers and 
develt>pers are trying to build the next 
great application. Some will socceed, 
some won't, but it’s a safe bet titai there 
will be more software available down 
the line than when interest in developer 
tools is low'en So, while most people at 
MACWORLD San Francisco w^ere 
focused on Apple's new candy-colored 
computers, I took a lot of notes about 
wliat's new in deveirjper tools. Read on 
for the details. 

Best New Tool 

DCon is a logging utility that every 
developer should take a look at. Logging 
uLilitles dt>n’i sound exciting, I'nii DCon 
migin just Ik* the exception. Normally, 
when a programmer is tracking down a 
l>ug, lie has to drop into liie debugger 
and trace through liis code, checking 
variahles as lie goes. If the hug is 
sporadic, this can he simply painful. On 
other [datforms, programmers can 


printfO to the command line, an<l finally on the Macintosh, so 
can we. Macintosh programming inclodes development at 
interrupt time, and writing extensions that need logging 
liefore a w'indow' can be l>rought up, but DCon works in 
those sUuatioas — it's Uiread safe and internipi safe, 

Insiailing DCon is trivial; just drag an extension into your 
system folder. To use DCon in your application, make sure 
the library to your project, add the l>Con.h lieader, ami use 
the calls dopen and dprintf for logging. Adding DCon to one 
of my active projects took less than 1 minutes. 
<littp://www.cache-computing.com>. 

The Compilers 

Metrowerks iniroduced CodeWarritir fTofes-sional for Java 
and CodeWarrior Academic for Java, products that l)ccame 
generally availal^le from Metrowerks and its re.sellers shortly 
after Macworld, The [iroducts are Java“f>nly versions of 
Metrowerks, CodeWarrior integrated developmeiU tcxds that 
supp^jrl development for C, C++, Java and Pascal. Metrowerks 
announced that the academic version of the Macintosh-ho.sted 
Java tcKifs will be included on the Apple Developer Connection 
(ADC) Student Program CD. Students visiting Metrowerks' 
IxKJth were excited about the availability of an academic 
version of CtxleWarrior for Java. Later this spring a tiew release 
of these tools will include easy-to-use rapid application 
development (RAD) tools for building graphical user 
interfaces, 'i'he RAD tools will include drag-and-drop editing, 
live component configuration, and source code generation. 

Many new programmers rallied around itie demtt of me 
Metrow^erks CodeWarrior Discover Programming for the 
MacinUrsii, a product For those have little or even no 
programming experience. CtKJeWarrior l^isc'over Programming 
contains the same Integrated Develtipment Lnvircinment (IDE) 
ibund in CodeWarrior Professional, anct includes online hooks, 
online (ulorials, and megahyte.s of sample code lo help get you 
started, <http://www.Metrowerksxom>, 


Michael Kutman now works at Network Telt^ysrems as a M;iciniasli Developer. In the pii.si, he 1ms Ixen an independeai 
contractor working on u variety tif [>rojt“cis, and chairman of MacHack. To contact Mklmel Rulman send mail to 
I rif K man iciTKxme, com. 
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KKAL Software deinonsiraicd ilie current release of 
REALhask as well as previewing an upcoming version 2 
release (scheduled for March), While version 2 contains a 
long lisr of enhancements, the two most irnpoitani feaiures 
([>oih of wiikh were denionsSirated at The Macworld Expo) 
are the Windows compiler and database connectivity. Yoirll 
soon be able to create a Windows executable version of your 
REALbask a[)p l>y doing nothing more than selecting 
Windows as the target at compile time. IIEAL Software also 
demonstrated the database features of version 2 which 
include a single-user, relational database engine and and 
connectivity to other database engines such as Oracle, 4th 
Dimension anti any ODBC compliant database engines. 

<http://www.realsoftware.com>. 

More Nfw Tools 

tlni Software Plus debuted their new VOODOO ,scrver. 
Uni is the manufacturer of the standalone VOODOO version 
control system and they've leveraged off of that prcxUul to 
create an easy iu use client-server architecture for large 
development projects. The VOODOO Server uses VOODOO 
clients (including a Code Warrior VCS plug-in) to offer 
reliable and robust version control functionalily witluHii a lot 
of the bureaucratic overhead that usually accompanies 
version control. Using a server ,shoukl make for more stable 
dataha.ses, and better performance walli multiple users. 
<http://www,unisoft.co,at>, 

whether youTe a one man team or part of huge 
development group, bug tracking .software is e,ssential lo a 
Umg term project. I've been using a Seapine's TestTrack for 
over a year, but after playing around with IHigLink 1.1 ai the 
show, [ boughi a copy of Btigl,ink. Normally, once 1 seiile 
into a prognint, I don't change systems easily. But, despite 
being happy with TestTrack. I feel that the effort of learning 
a new^ system is wtII wonh the advantages BugUnk offers. 
Some of ilic feaiures in BugLink make me think that there is 
a full database behind it, Bug reptm lists are done as queries, 
and they are ea.sy to set up. ‘I'he trac'king sofrw'are is very 
fast, and com|)letely noivmodal. That means, you can have 
tw'o windtjws up at once, so you can compare bugs. 1 was 
also pleased lo see I could have multiple lists of bugs wdth 
different criteria, and have bugs matching dirfcTeni criteria in 
each window. BugLink, as well as being multi-platfbrm, gives 
the user the feel of a good, qualiry Macintosh producL 
<http://www.pandawave.com>. 

Kesorccrer 2,2 has been out for a while, but not 
everybody has upgraded. You can download a free upgrade 
for iljc 2.0 pnaluct, and it’s worth geUing for the Appc-arance 
Manager support alone. Resorcerer, of course, is the 
commercial alternative to Apples free resource editor 
ResEdit. Recentty, ResEdil has fallen Ireliind rm Apple's 
technologies, and today, there are resources that can only be 
edited with Kesorccr er. i his is making it a must have product 
(even if the high price does put it om of range of siudcnus 
and hobbyists). <http://www.math€maesthetics,com>. 


Anotlicr tool 1 find indispensable is the code editor 
BBEdit (by Bare Bones Software). BBFdit, for years, has l>cen 
the only reasonaljlc w^ay lo search and compare files on the 
Macintosh. A year ago, Metrowerks w^as an acceptable editor, 
but BBEdit was required to do anything beyond one file at a 
lime. Today, even though the Metrowerks' IDE has seen a lot 
of advanced, BBEdit is still one of the best tools for editing 
code, <http://www.barebones.com>. 

Nlcworking Tools 

More anci more, Macintosh developers need ways to 
connect to t>ther computers. In addition to networking 
Macintoshes together, developers need to access other 
platforms. l oitunately, there are ne%v tools for both these needs. 

For developers of networking hk>1s, the must have 
producL is AG Group's Ether Peek. The price is out of range 
for all but the serious netw-ork developer, EtherPeek snemps 
oetw^ork traffic, which means it gratis every packet on the 
network and disiilays ilieni. Filtering incoming packets is 
easy, though I would like the ability to filter packets already 
received, in addition to basic snooping, EtherPeek has 
dectnlers for .siamlard fiackei ty|K\s. and adding decoders is 
easy. EtherPeek also lets developers send packets. 
<http://www.aggraup.com>. 

There are ihrcx.' solutions lor communicating between 
Macintoshe.s and windows machines. DAVE allow.s Macintoshes to 
mount any Windows volume <http://www,thursby.com>. COPSTalk 
lets Windows machines mount any AppleShare for FileShare 
vtjlumus <http://wwwxopstalk.com>. NetWare lets Macintoshes n^ount 
IPX v(>lumes. <http://wvi/w,prosofT.com >. Hat'h of these pnxlucis iias 
Ixx^n reweti lor TIte Maxvvorki F:xpo. so T you need iliLs kind of 
conncLlivity, j)lL*iLse dteck tint llieir web sites. 

For connecting to the Internet. Sustainable Softw^orks 
http://wWW.sustworksxom has an Internet router running on a 
Macinttish that is quite impre.ssive. Wliile there are other 
routers that run t>n the .Macintosh, tl^NetRouter r,s amazing in 
how far they have gone. One of tlie drawhacks to the growth 
of tile Internet is stinginess with IP numbers. Many ISP's now 
charge for anyone using more than one iP address. Witli 
fPNeiKouter, yon ('an have tiitihiple mat bines masquerading 
as the one running tlie router software. I have seen other 
so kit 10 ns, and this one seems the most complete to me. In 
addition, there is IPNetMonitor w hich has a lot of diagnosis 
tools for the Internet. 

Tools FOR THE REST OF US 

Not everyone wants lo program in C or Java. Many 
projects are better suited for other environments, and there 
were a few' at the show^ Tlie three that caught my eye w^ere 
40, ReportMilL and AgentSheels. 

4D is an estalilished prcxlud, but one I haven't explored 
l>efore. ITiis year i sat down and ACI US showed me just how 
use fui and productive iP V6 is. ID V6 is a rapid applic ation 
development (RAD) tool and also a rehniunul database 
management system (RDBMS). Product.^ such as FileMaker are 
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useful for some purposes, but to get real |X)wer, you need a taie 
RDHMS environment and development suite. Unftjritinately, 
most relational datal)ase products are jnind-numhingly complex 
—' 4D V6 shows that ilierc is no need for complexity. 

ReportMill is a WehOl>jects pro^'ram for creating 
dynamic reports on the web. ReportMill leverages off of 
WebObjects to create pdf files on the fly. An example they 
were showing involved a u.ser selecting topics from a catalog, 
then receiving a catalog custom-made for their use. Unlike 
other similar solutions, this catalog is a pdf file. HTML 
formal!ed results are nice, but pdfs give a whole new level 
of control over whar ihe output looks like, and how it [irints. 
Nothing is worse than a page looking great on one browser, 
but not another. <hltp://wwwjeportmil!.comx 

AgentSheeLs is a nice modeling environment, Imt F 
believe it is much more powerful tlian they are advertising it 
to be. Basically, every element on the .screen is a 
[irogranimahle agent. One of the examples denionsiralcd was 
a small city with roads, cars, stoplights, and a train. Each 
element on the screen has a simple program frjr movement. 
The language used is graphical, and easy to understand. 
Furthermore, once everything is done, it can be converted to 
a Java applet and uploaded U> a web site. Not cmly does it 
provide a good learning environment for new coders, its 
power makes this a u.seful tool for professionals with the 
need for model, <http://www.agentsheeis.eom>. 

As every* developer knows, some limes we tTash, 
sometimes we crash a lot. And, as every developer realizes, 
(Tashing dcx?s bad tilings to u Maciruosii. Tliere are all kinds of 
repair utilities, but IVe only seen one that sevins to check 
everything, and dial’s TechTcx>l Rro 2. TechTtKils dt>es things 
right, 'lliey ship on a bcxnablc disk, which should not even be 
worth mentioning, hut too many disks 1 would expect lt> be 
bcx)table are not. TecliTooIs lias 3 modes, simple, standard, and 
expert. 'I'he simple mode is simple enough, just select a volume, 
and click “Check". It will then run thrtuigh a comprehensive 
test. The Exjxjn tiKKle is very nice, and easy to navigate. There 
are a LOT of tests, but tiic manual is very w*ell wTitlen and give.s 
extra information lor the curious. Normally. I feel that if T need 
a manual, the software is pcKirly written, but this Is not the citsc^ 
here. 'I'he product is easy to use without the marniaf hut the 
manual is an enjoyable read while your computer is 1x4ng 
fixed. Ponunaiciy for me, bur unfortunately for the review, 
none of my disks needed fixing, 1 t:an't vouch for how' well 
it fixes things, but as 'fechTcxils has lK*eti around for a while, 1 
am cofifident tliat it is a quality prrxluct. The other lesLs. such 
as hardware, connection, and system tests, were simple to run, 
and the results were quite interesting. There are 51 c:ategories 
of tests, making this the most complete .solution Tve seen so fan 

Another new release was AppMaker 11. AppMaker is a 
framework and tool for rapid developmeni. Us a mature 
environment, and constant updating, has made tlus a gtxnJ place 
to start any new projects. The latt^st releiise includes Ix^rter support 
for the Appearance Manager, CodeWarrior, and more flexible 
ixinels li.sLs. Bowers Devek)pmeni pre\4ewed a ux>] for inifxming 


FowerPiani objccLs into MFC. Vor anyone who has ever tried this 
manually, this is a major Ixxius. <http://members.aofxom/bowefSdev/>. 

Itiere are two major installers for the Macintosh, Mind Vision’s 
VISE, and Aladdin's lasrallerMaker. For years, InsiallerMaker has 
leveraged off Alladin’s Stulfii engine to ix" the dominant installer 
for Macintosh applicaiioas. Alladin did not have a new' rekra.se for 
tills Macworld, but expects to have a new' version out sometime 
in March or April, <http://www.aladdinsys.com>. 

'rhe new' release of MindVisioiTs VISE now features weh 
support, including the ability to update over the Internet only 
downloading the parts needed. Another new feature 1 like is 
the updated configuration tools. VISE has added more 
functionality to their already existing packages (subprojects 
inside of a main insiallatifm package) making U more 
powerful and flexible. <http://www.mindv[sionxom>. 

But Wait, Isn't There More? 

These are the products 1 saw at ilie show. Macworld is a 
huge show and there were certainly some uk>Is 1 missed, but 
I hope this gives you an idea of what’s new tools are now' 
(or soon to be) avail able for ilte Macinussh developer. See 
you at the next show! El 
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PLUGCIM-IM 


By Hvan Trent 


Writing a Module for Document Express 


Harnessing the power of 
Document Express' email 
and database engines 


Bulking Up 

In the riKKiern wDrkI of the information 

even the .smallesi coqKjralitHi canntu 
afford to manage its various forms of 
communication ineffetiively. HlectnmU mail, 
in paninjlar, has t|ukkly Ixxxmic the mtxsl 
unruly form of communication from a 
mana^eria! and administrative perspeelive, 
■|he sheiir volume of email which even a 
mere individiuti must prcK’ess during any 
given work day can often ,seeni ebtlining. 
However^ email is also a t>reiioas 
eonitnodiiy for any corixiration or individual. 
'IIk^ names of cusiomers, their asstK'iaral 
order informatiem, prol>lefn, suggeslion, and 
even lui\ch date confirmation, i.s IcKked 
siifely aw'ay on axintles.s hard drivtis on 
countless corponiiions' compuiers 
throughout the world. 

Much thanks to a new s<iftware 
application. Document Kxpres,s (or DR), the 
task of providing the fancy features of an 
automated and well managed em;ti] system 
hiis Ix^en rethiced to a simple setftjence of 
keysinokes and mouse clicks. LX'iaiment 
rji[>ress is advertised as an “interaclive 
nelatioaship management system” and fhai 
dcseriplion Ls certiiinly quite appitjpriate. 
DK’s mexst obvkms selling point is in its 
hrrxidca.si eiTrail cipihilities. btii that ts hardly 


the limit of DEs communicatioms arsenal. DE am send out 
jXTsonalized rc^^poases to emails received fwm any FOI\^ mailbox, 
lliLS am prove particularly useful wlien managing dtta^athering 
HTML-based foniis and providing the user with automatie 
conllnnulion of tlieir submLssi<jn. So wltile DK Ls, at iis simplest level, 
a brcKidaisf tiKtssaging system, it is really much more: it s a cTintact 
management system, lH3F3/SMn^ email engine, interaaive email 
system, and extensible applioitiun with a ptjwerFul and well 
implemented plug in architeciyrti. 

I was first introduced to Document Rxpress when 1 reviewed 
version 1,0 for Almut This Particular Macintosh 
{http://ww^.atpm.com) in August of I99f^. Murk Teixeira, 
£ level ope r of [document Express, contacted me immediately 
following the puldicatitm of the review and conveyed a genuine 
desire to improve \W. as per my criticisms. Recently 1 received 
another email from Mark announcing that version 2.0 had been 
relcascxi unci tiiat he would like me to re-evaluate Dcxurneni 
Express in another review^ for ATF-Vt, Aware oflhe fact dial 1 am, 
aside from an overly harsh reviewer t)f Macintosh software, a 
C/C++ programmer. Murk asked me if I w^ould consider writing 
an article discus-sing the development of a DR: plug-in using the 
DfX'ument Express SDK. After reading lliixiugh the SDK 
d<K umentalion I wa.s con\ inccxl that thi.s task would he fun and 
only mcxlerately challenging much thunks to the strong 
ckK’u mental ion Mark has prov ider! wilh the SDK. 

M0DIIL4TING A Bozo’s BimUDAY 

'I he Diibert era has !>n Might fodh a trend of intra-corponite 
etnail cksticissing everything from hkmde jokes to IxKird meetings. 
Some examples of the stibjCTls of the.se tniaifs might lx;: Your 

Clex’k, Vacation Schedule, VCivkly Meeting, Daily Units Sold, New 
lk‘ta Release, Training Seminur, liozo Submit Your Timesheet, and 
tnost importindy Happy Biiihduy! Corptinite relanxi emails are often 
ciiLinks of text with very slight variations from rc-cipicnit to recipient. 
Wouldni it f)e nice if a Mae ctxild aulomatiailly genc’rute email 
messiige^v Ixuscd on submLsskjas rcreivcxl fftjm an Hi’MI. fbmi, for 


Evan Trent (evan@sovcT.ncl> is ;t first yc'ur .student at the University of Chiogt) dmp://emLfh.uchicago-edu). He serv'cs as the 
Review's Editor and co-w^ebmaster for Alxjut This I*articular MacinUxsli (lnip://www.alt>in.eoiTt) a fret' Macintosh e xine. He ha,s 
Ix’cn prt>gr*imming in C/C++ lor .‘x^veral years now as a h£>hby. 
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example? Imagine ht>vv this could simplify and expe<liie operatitins. 
Tlus will lie OLir task; to develop iirid anplcjiicnt a DE module 
which, iiaseci on a siihmLssion Iroin an 111 ML fomi, generates anti 
delivers a perst^nalized email announcement. We w'ill aill diLs projm 
Bozo’s BinJidiy. 

dhis module w^ill fiinction much as expeaed. As dictated l^y a 
user defined time interval tiie module will cheek a user defined BOH 
maillxjx for new Bozo Rinhday messages. Tlie resulting emaiKs) will 
then lx* [Xtised and jMtxessed ft)r jxitinent data. Tlx^ data from ilic 
ematKs) wall then lx used to genmre an outgoing message based 
on a pm-defined template, or in DE terminology: mallform. The 
iiKKlule will tlien send tile t}utgoing message to all llie marked 
entries in the cuiTently open DE database tile. The piixess is entirely 
automated and nearly every variable may be assigned a value 
raiioLely vkt llie LFTML fonii, 

GEirtNC Started 

r^xument ExpR‘s.s modules are Codti Rt?souR:es, just like 
IIypei€aid XCMD's or 4D externals. They may contain additional 
resources as needed: Dialogs, Menus, strings, icons, etc. Each code 
re.souR:e has a main entry point, with a clatrly defined p^trameter 
list, or prototype. Tlie main function must lx defined pmjxriy^ or 
the module will not link. The prototype definition for die main 
function ('an be found in the file McxiuleCallhackh, which is 
included witli die DE SDK. 

CallBacks 

Dcx:umenl Express has implemented a number of aillback 
routines that imxiulc developers will find essential in ea'ating DE 
modules. 'iTiese atEback routines are accessed by a global pointer 
which i.s pa.ssed into the mcKlule at initialization time. 
'^MtxluleCallirackJi” defines all of these callbacks and pRwides 
handy macTOS to call these functions from a module. 

DE tailbacks are grouped together loosely based on the general 
class of functionality. DE supports callbacks for window 
management, database access, menu and palenc interaction, contact 
and document manipulation, plus many utility callbacks to assist in 
drawing, spell c'ha:king and wx)rl<ing with dialogs. !>ocument 
Express also suf^jxirLs POP3/SMTP dmjugh TCPCallbacks, a fully 
implemented email engine which can lx used from tlte SDK to send 
and receive email messages, the POPIVSM'FP callbacks are 
liighlighled in greater detail later in this article. 

High Ijevel Event Basks 

Dexument Express maintains an internal array of open 
nuxJulcs, and [rasses tliesc mcxJulcs high-level cvenLs when 
appropiiate. When a module receives an event from Document 
Express, it must first determine the event’s high-Ie\^el message 
gjx>uping. TIktc are seven diflercm messages groups: 

H_Sys™_MESSAGE 

H_HX)L^SSAGK 

ILWINDOW^MESSAGii 

U_DATA]iASE_HESSAGE 

H^BUTTOH^MESSAGE 

H_J1ENIJ_MESSAGE 

H MERGE MESSAGE. 


An H„SYS1 HM_MESSAGE gets passed to a module at important 
startup and sliutdown (HS_INTT[ALI2E and HS_CLOSE) lintes. 
Additionally, lISJDLE is m\i to a module [xricxlieally (note tlntt 
^'w'indows” get their own idle mess:iges). HS_[DLE proves usehil in 
keeping track of timer value for a trigger. RS_HrnE_AI.L_WlNltOW5 
and 1IS_SHOW^ALL_WINDOWS are system messages tliat are uscxl 
to manage a module's window<s). 

Dcxaiment Fxpre,ss will handle drawing a mcxlule’s icon suite 
in llie UX)l palellc as well. All llie pnigramiucr need do is pRivide 
DE with a liMLs’ resource which |x>ints DE to an aiTay of ‘cicn' 
restnirces. Three consecutively numlXTed 'den' resources must exist 
for a iTKxlulc: an icon for “normal” state, "pressed” slate and “at'live” 
state. DE tracks iiioase clicks on the jxilette aLitomatically, and Is 
responsible lor maintaining the various icon .skates. 

Occasionally, it may lx desirable to draw a figure or shape in 
the palette dynamically. In this event, a module must not SLipf>ly a 
default icon suite, and must listen for specific ILTOOL^MESSAGE 
messages. Tlie selectors which further define HJIDOL^MESSAGE 
are nurneraus. Generally Sfxxiking, a rntxlule will lx notified when 
it must draw each [:>ait of its owned rectangle: the Irackgiound, 
contenLs, name, and the three icon states. When a module must 
perform its drawing, DE take's care to set llie window port, dipped 
to the icon’s rectangle. DE wiil lustoie tlie jx>n wlien drawing lias 
completed. 

The majority of the source code for a mcKlule will appear in 
die window class, Tlie DE message H„\!C^NDOW_MESSAGE, 
and its accompanying 25 selector messages, provide a developer 
with ample power to manage even the most complex window 
scenarios. Familiar high-level Madotosh events are translaied 
into 1IW_,KEY, nW_UPDATE, 11W_CLICK, MW_CLOSE, 
HW_ACnVATE, HW'JDLE, HW_CURSOR_CHANGE, and 
HW_DEACnVATF. messages. 

The Document Express database message 
H_DA1ABASE_MESSAGE is sent to each modiiie w4ien a diange 
(xcurs to a DE database or a database record. For ex^imple, a 
mcxlulc will lx notified wtien a new tkiialrase lues lieen opened, 
created or dosed (irD_OPENJ)ATA_nLE, in)_NEW_DATA_Fni:, 
nr)_CLO,^E_DArA_FlLE). In addition, changes in a cxintacT entry 
record generate messages as wxdt (ETD_EMTRY_ADDED, 
ITO^IiKTRY^DELETED, HD_ENTRY„SET, 

1 m_CUlddiN”l'_EN4Ky_a lANGED 

Creating and handling buttons in a module is relatively 
easy. The SDK defines a buLlon bar array, wliidi DoeumenL 
Express manages internally, This array was designed to provide 
developers with a means to conform easily to DE’s interface. 
DE’s in was engineered around ihe concept of limiting multiple 
open windows by providing separate “views” within a single 
window. Changing views usually means maintaining separate 
button groupings. Tlie module SDK allows a module lo easily 
manage several different button arrays, and handles tracking 
and displaying these arrays automatically. 
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Figure /* A mi)fMe*s window and button bar. 


Document Kxpres.s offers the developer oppfjrtuniLies to 
respond to the DE menu system by passing a module various 
menu messages at appropriate times. If a module’s window is the 
front most window, DE will send messages asking if a partiailar 
menu iletTi sliould [)c enabled or disabled. The itKxlule will l>e 
sent a liM_COMMON_CAN CHOOSE messages when one of the 
“common” menus (Apple, File and Edit) is cEcked. Likewise, a 
mcxlulc will be notified when a choice has been made via 
HM_COMMON_CHOICEMADE. Tiie definitions for each 
“common" item can he found in the ModuleCallback.li file. 
Additionally, modules may place their own menu(s) in the menu 
bar, and they may also append the Apple, File and Edit menus at 
pre-defined places. 

Rounding out the message suite aie 11_MI‘RG1LMESSAGH and 
H_C0MJV1AND_MESSAGE. The. former will be sent to a mfxiule 
when a “merge" condition arises within a Dtxumeni Expmss 
document, usuaEy at times tefore Print or Broadcast. Tliis flexi!>iJity 
allows modules to maintain their own meige cLata, thus expanding 
the merge capabilities to include not only the 32 built-in coniaci 
ndds, t)ut additional fields with tfieir own sources of input. We will 
discuss the If_MIiKGE_MESSAGE in greater detail later in tlus aiticle. 

An H_COMMAND_MESSAGE will be .sent to a module if it 
is specified as type “Broadcast Capable."’ Modules of this nature 
are assumed to be able to handle some sort of communication 
with an outside port or service and are responsible for 
broadca.sring the contents of a dcxiiment to a select group of 
recipients. The H_COMMAND_MESSAGE selectors are 
1LC0MMANDJN1T_SERV[CE, i[_COMMAND_SEND_SKKVlCE 
and H^COMMAND_Ql]IT_SERVJCE, Document Express 
supports broadcast email iniemally, and broadcast fax via 
dedicated ISP’s, or through FAXstfs fax software (see the 
module Fax Browser). 

Each mes.sage group has an ac:companying selector set, wfiich 
foitiier defines tlie highcTdevcl message. For example, when a 
module window neceives a mouse click, tfocument Express will 
fxiss the mcxlule a H_WINDOW_MESSAGE, with the accompanying 
selector HW^CUCK. 

FotturuUely, tlie module class lib rary oiganizes the message 
groLifX'j aixl iiieir accuiupanying seieclors into a weii-ddlned uljtecl 
tjricmied dispatch mechanism. 'Ihis construction alleviates the need 


to wTite any high level dispatching code, and allows you to work 
with DE messages within a familiar object formaL 

The scope of Ifozo's Birthday will require us to override just 
one class: the IlWindow class, lliis class handles the dispatch of 
window related events such as mouse clicks, update and activate 
nressages, idle messages and so forth. will override this class 
with a new class c^Ued BBWiiidow. BBWindow provide us the 
framework for adding our own ccxle. By overriding the HWindow 
class with our own BBWindow class, we can receive the more 
appropriate DoClick message, with die more useful Point and 
Modifier parameters. 

Creating tfie Project 

The Starter Projea tliar accompanies the DE SDK wil serve as 
our fyasic framework as it supports the basic implcmeniation of a 
DE mcxlule. AdditionaOy, Starter does a nice job of incorporating 
the DE module class library, which in turn organizes DE’s system 
of sending high level events into familiar and predictable classes 
and class methods. 

In the mainO [unction, found in die file mam.c, we will be 
listening for the H_SYS1EM_MESSAGE message, witfi die seledor 
HS_[NIT1AJJZE. Tliis message tandem gels passed to each module 
at slanuf). Wlien our mcxluie receives diLs message, it must first 
create die IlModule object, lliis object manages the class library, 
creating internal objects for contaa management interaction 
(HG)ntaci), internal message dispatching (HDispatch), tool palette 
interaction (HTcxilPalette) and a preferences object (ilPreferences). 
One may ignore the.se classes entirely, but they must be set up at 
HSJNl'riALlZF time. Now we cxn create the BBWindow object. 
Once created, we will initialize ifie class, and alkxate a window widi 
the appropriate dimensions. Document Express automatically 
handles opening, zooming and closing module windows. 

listing 1: Main Entry Point Into the Code R^ionree 


main 

pascal long main (short tncssageTypt*, shorL inessage. 
long paraml, long param2 ^ DEParamsPtr hPtr) 

i 

long result =’ 0: 

EnterCodeReacfUrceC); 
switchf messiiageType ) 

I 

case tL_SYSTEM_HESSAGEj 

IfC meesage = HS^IHITIALIZE ) 
i 

// .sctup/itmcitihcr tjur git jbiil poinicr ;uid imjdulc ID. 

deParamsPtr - bPtr: 
gModulelD - paraml: 

// Setup lilt: cniai) interlace 
setUpTCPCallbacksO; 

// aJkKaitf tairubjeLts. 

gModule new HModule: 
gModule >IModule(): 

gWindow = new BBWindow: 

({BBWindow*) gWindow) ->IBBWliidow(gJ^o<iiiieID); 

// - 

li#Rr<egisterMergR¥j el d (paraml, *B0Z1") : 

WRRegis terMergcFleld(paraml^ * B0Z2"): 
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WRHegisterMergeField(paraml» 'E0Z3'): 
WRRegistetMergeField(paraml♦ 'B0Z4'); 

I 

else result gD1 spat ehOHandlG SystettiMe a sage (mesa age* 
paraml ^ para3n2) ; 

ExitCodeResource C ): 
return result: 

1 

In Lhc flic BBWlndow.q), wo will define one mediod, 
[UBWindow. In this tnetliocl we will alloaite our window. 'Ihe 
superclass method HWindowdWindowO is tlie e^isiest way to create 
a Dcxurnent Express '‘style" window. IWindow is iosfX>nsible for 
nuinaging tlie Macintosh WindowPir and registering the window 
with IJoaiment fixpress. 

Listing 2: Allocation of a Module's Window 


BBWirHl<iw::IBIJWlndc>w 

void BBWindow; iIBBWindowdong aModuleTD) 

( 

HWlndov::IWindow(aModulelB < zoomDocEroc + 

MIN„WINDOW_WIDTH. HIN_WIfJI>OW_IjEPTH. HAX„WiNDOW^DEPTin 
^^A3C_WIND0y_DEP'rH. FALSE, FALSE. ■■\pBozo 

Birthday"): 

J 

Next it is necessary to create a button and place it in the 
BBWindow window^ Luckily DE offers programmers the high-level 
t(X)is needed to make a rncxluie’s apfxarance conform to die DE 
interface. For example, DE has a well-defined button scheme 
which enables programmers to establish a stanckrd inreiface 
aerrass all of their mexiules. 


When pressed, our button will log on to a POP3 server, and 
check for new messages. Tn the BBWindt>w.cp class, we must 
override the mcilKxl InitButtonBars. This mciliod is called during 
I rWindow::IWindow. Overriding this method offers us the 
oppominity to set up the window's button bar array with 
controls, and allows us the opportunity to provide specifications 
regarding the control's characteristics, for example: behavior, 
appearance, function, 

Listitig 3: Initialization of a Button Bar 


BBWindow: :lnidkjUoDiknj 

void BBWindow:: Tnit.ButtonEarf;() 

I 

^define kNumberButtonBars 1 
iMeflne kttumberOfButtons 1 

buttons-)numberOfButtonBars = kNumberButtonBar^: 
buttons->btittC5ELBarsf0l .number Of Buttons = kNumberOfButtons: 

// thu button witJi a t:allbad< routint?, name, type and icon artwork. 

buttons-!>buttonBars [0] .buttonti [0] .clickFroc = CheckForBozo ; 
buttons->buttonBars[Oj .buttons[0].name = 

MakeButtonNamePti: (kButtonnames. kCheckNowName); 

buttons - >buttorLBars [0] . buttons [0] -type=* 

H_BirrrON..TRIPLE CICN COTL: 

buttons >buttonBars [0] .buttons [0]. icon IT) = 
kMBoSoniethirigNowlconGroup: 

I 




Mac, go out and touch the world 

ADR I/O Icis y^jur ajslomcxs^ Mat^s ainbol things, it lets them feel. 

ADB I/O lets tlie Mae be part of the physical world. 

ThDusands of Uses 

Sdence, Multimedia, Qiildren's Museums, Home /Automation, 

Theatre Stages, Industrial Testing, Medical Resr>^arch, Bonsai 
Watering, Robotics, Weather Stations—anything dial tan 
be electronically measured or controlled can use the ADB I/O. 

No Serial Ports Occupied 

ADB I/O uses the Apple Desktop Bus to communicate inputs and 
outputs to and from your Macintosh. (Maximum polling frequency 
is 90 HzO No external power supply Is needed. 

Eight I/O Channels Provided 
Four relays for output Four channels for Digital In, 

Digital Out or 8-bit Analog In. 

Extensive Software Support 
With ADB I/O and nearly any environment,* 
it is easy to build customized 
applications for your control and 
data acquisition needs. 

For more info, visit us at 
WWW, bzzzsucz.coffi. 

















When the button is pressed DE will jump to the address 
specified in the clickProc variable. Prom this clickProc inethcxl, we 
will directly call tlie RBWindow via the ^Window global We 
do iliLS Ix^cause it is a good organizational strategy given the 
register setup and restoration we must perform witliin the button 
press callback, 

ptiscal void Chet:kForBoiio(ClickEvGjJlE’lr ft*/. 

ButtonDefFtr fb*/. 
short /*dioiceV) 

1 

// setup and restore A4, as we are ciilled directly Ihitu DE 

FiTterCodeReBourcei 0 : 

C (BBWlt] dow *) gWi nd ow) >CheckFo rBozo (): 

EKitCodeResoorceO : 

[ 

Once witliin tlie code attached to die clickPioc variable, we c'an 
now perfonn the task of logging into the POP3 mailloox and looking 
for messages. The DE SDK comes with a header file which we need 
to include with tlic [>nijea headers if we wish to utilize DE’s email 
engine. The file TCPQillbacks.h defines a complete implementation 
of POP3/SMl‘P. Using these funaions gives us complete amtrol over 
a POP3 e-mail box and a messaging iraasport server (SMTP). To 
access tliese methods, we must first declaie the TCP global variable 
TCPPunctionsl^ ICPPtf in our code. We mast then call the hmetion 
seiUpTCPCallbatks, preferably at module inii lime. After calling 
.sell JpTCPCall [racks, we can tficn use the e-mail callbacks (refer back 
to the function main), 

Email Euphoria 

D<x:unicnt Express’s SDK makes it very simple to establush a 
connection witli a POP3 mailbox. Piist, we must establish a link to 
the email engine by calling the function FNewConnection. 
ENewCcmneciion rctym.s a long wliidi is used as a jximmetcr for 
every subsequent email function call. ENewConnection tiikes two 
parameters, the global module ID and a Ixiolean which indicates to 
the engine whether or not it shcjiild display a status window, 

long connect = liMewConnection IgWodtilelD. TRUE} t 

Once die cx>nnectjon has been initialized, we must register our 
logon pammeters with the email engine. 

ESctliOgon (EModul el D, connec L, 

"popusernanic-, // PC)P3 ;i^'-r niimc 

"oiail. yourserver, codi‘' , // POPS nuiJ server 
“Xp". // etiipiy tised for SM'i'P 

“your pas sword"): //POP3 password 

finally^ we pedbrm the logon. Document Express will handle 
enrjis iniemaily and display the app!x>|>riale enor rnessiige widi an 
error ccxle. 

OSErr err ” EPOPLogon{£Modu].eID, connect) j 

Now tliat we have csiahlishcd a connection with the lemoic 
mail servt^, our next task is to check fc)r new messages. Tlie easiest 
way to di) this is to tiuery the senver for die am^nc message count 

long totnlCount: 

OSErr err ^ EPopKsgCount(gModulelD, connect, StotalCount): 


For die sake of Bozo’s Birthday^ we will employ a simple 
strategy' of iterating diiougli each message on the mail server, and 


looking at die message header only. Specifically, we are going to 
!cx>k at eac:h message’s subject header, kxiking for email messages 
tided Jx>zoJ>irt]iday_. Once we have ent'ounteied a message with 
this subject, we will download the body of the message and parse 
it for the pertinent data. 

To accomplish this, we use the EPojiMsgTop function, 
which allows us to only download the message's header 
information. Once the message header has been downloaded 
locally, we can use the query callback EReadlField to access die 
data found in the message header. 

long foundBozD “ 0; 

for( long i = 1 , i <“ totalCmint; i+4 ) 

( 

Handle h; 

Str255 subject; 

err “ EPopMagTop(gModulell), connect* i, 0* NULL) : 

h = EReadlField(^odulelD* connect. enLSubject) 

1f{ h t= NT.IT.L ) 

i 

lILockdi) ; 

C2PStrCopy('h* subject); 

DisposeHandle(h): 

if( Equalstring("\p .bozQS_birthday_", subject* 0, 0) } 

I 

foundB oko " i: 
break; 

1 

I 

I 

Once we liave identified a _bozo_birtiiclay_ message on our 
mail server, we can then download tlie message from the server 
using the HPoplVl.sg[tad function, w'hkii retrieves the entire 
message. The last parameter whidi EI’opMsgRead takes is a Boolean 
which deteniiines w hetlier or not the mail .server .should delete the 
message after it has iieen downlmdetl it. A value of TRUE signals to 
the mail engine to delete the messjrge. 

Ift foundBozo > 0 ) 

err = EPopMsgReadCgModulelD* connect. foundBozo. true): 

We have now succc.ssfully cieatcti a connection to a POP3 
maillxix, detenninetl tlie message count, iterated the mail box and 
downloaded a mes&ige. At this point, there may lie some confusion 
as to how the Jx>zoJ)irihday_ me.s.sage ever got .sent to that POP3 
maillxjx in tire first place. Anotlier source of conilision may lie the 
format of the message. Before we go any further, we w'ill digress a 
little into the m^igic of nijiilft>rms, anti ifie Ix^auty of paramalerized, 
smart email messaging. 

Smart Emaj] 

Document Express takes a uniejue appnrach to Email 
mes.saging. DE views Email as data whicli c'an lx; regarded in tlie 
Siime Lxintext as daialiase records. lliLs Is a perfectly reasonable 
appraich: each Email record resides in its own flat file databa.se on 
a remfxe server, and can lx; accessed via a .simple query language. 
Tlie sdieriia of an Email lecord Ls trivial; a header, which gives 
addressing and format informtition, and a ccMainer for the message 
body, usitally text, but sometimes piautes, .sounds, file enclosuics or 
odier ari>itrary data. 
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n<K ijmcnL Fxpres,s’ Webromi is a perfect vehicle Tt> fx.1ter 
illuslrate the workings of parameterized FmaiL Wehfomis 
employ FormMail, a mcxlifrcaiion of Matt Wright's PEKL script, 
which can (organize data from an HTML form into a 
parameterized Email message. Typically, a visitor to a wcixsite 
will encounter a form, type values into fields and/or select 
items from popup menus, lists, check boxes and radio buttons, 
Wlien llie user presses the Submit button the HTML C(xle 
fxiints to a CGI, in this case the FormMail PERL script, and lire 
HI'l'P server senrls the daia frt>m tlx' form on to the CGL At 
this p<nni FormMail takes over and neatly packages this data 
into a well-defined email message and delivers it to a pre- 
defined email account. 

Setting up a Document Express' Webfonii to capture data is 
easy. Ii is iltc iXTfect way to administer an interactive welxsiie. 
For Bozo^s Birthday, we need to capture only four pieces of 
information to sucrcessfully implement our task; Bozo’s name, 
hirihdaie, [rarty lime and legation. 

Before we can use our HTML form to capture the Bozo 
vitals, we must configure it for use with FoiniMaiL First, assign 
a siiliject U> the I'onii. This subject will ix; used later to determine 
if the email is a Bozo Birthday message. Secondly, we need to 
assign an address to which FormMail should deliver the form 
once ii has lx!en prtxesscd and turned into an email record. We 
can do this with the following two fines of HTML code. 

< input type="hidden'' name ^’^eubject" 
val hi i:T.hdiay_”> 

<iriyuL LypC!'"“ti i dden" tiame "“recipient" 
value="soitte@Lid(lress. ccnifli‘*> 

Now that we have added die constants, so to speak, we can 
setup the lhrcc‘ data fields to capture the Bozo variables: 

Bozii's Name; <inpiiE text* name ='‘Niinic™SIZli=3tl 
MAXIJN(iTH=5U><hr> 

UiniKlalc: <inpuf rj'pc^XcxC* name =''Bday'' SiZEr=3n 

MAXLbNtrn l=3(»<br> 

Locittioji: <iiipii l ly pc= text " mime = "Loc" StZF=3f) M AXi ( iTH “3( >><br> 

Time: <iiiput type^’' lext “ nanic = "' rimt ^ S1ZE=30 MAXI.ENGTH=3ii><br> 

The resulting Email record, processed by FormMail and 
delivered to the destination Email address, will have roughly the 
following Format: 

Name: Johnny Rocket+_+ 

Bday: February 20+_+ 

Log: the patio tecrace+_+ 

Time: 1:00 P.M.t + 

The data values from this form will be packaged and 
sent to the email box some@address,com. The next time our 
mrxlule checks the email account, it will encounter the 
_lx>zosJ>irLliday_ message, download it, parse the fields 
Name, Bday, Loc, and Fime, load ihe values into our own 
special merge fields which we have [ircviously registered 
with Documcni Express, and send the message to all the 
marked contacts in the currently open DE database. 

Magnificent Merge Fields 

One of DE's many neat tricks Is its ability to merge data 
from any of its '52 contact database fields and deliver a 


personalized message to members of a database fike 
Additionally, modules can create and maintain their own merge 
fields, so adtiing data, which is lieyond the scope of the internal 
contact system, to a message is possible. In our mail Form wc will 
warn to use the Bozo's name, birth date, parly time and location 
information in addition to the recipients' first name. When the 
message finally ends up in the recipient's in lx>x, it will read like 
tile following (the data in BOLD indicates data which has been 
merged into the message IxTore it was delivered). 

Dear Fred. 

We would like you to join us in colubraiIng the birthday 
of Johnny Rocket on February 20 at the patio terrace at 
1:00 P.H. We will be serving coffee, soda, cake and ice 
cream. 

Looking forward ro your presence* 

Linda Sunshine 

Personnel Manager 

Dot'ument Rxpre.ss has implemented a clearly defined 
mec:hanism Ibr allowing developers the means by which tliey 
can add their own merge data to any DE d(K:iinierU. To register 
our own merge fields, we tlie DFi callback 
WIU<egi.stcTMeigeField. In addition we will lie listening For two 
messages tliat will be passed to us at the c:nx:ia[ times of 
substitution, HMM_ORTjnn*F and HMM_GE1’_TEXT. 

We will go back to the module initialization routine, 
described at the beginning of our discussion of moduies. We 
must register our merge fields with Document Express at 
initialization time. Once our meigc fields are registered, the 
end-user, who is creating the mailform document can select 
our merge fields from the list of Fields. Our fields will appear 
at the bottom of the field popup menu, can lx* placed in any 
document, and will appear seamless to the user who is 
creating the mailform. 

To register our Bt)Zo merge fields witli DE, we use the 
callback WRRegLsierMergcFielcl. The first parameter to 
WRRegisierMcrgeField is our global module ID, and ihc second 
is a 4-char OS'Fype, w'hich identifies the merge field. Note that 
these 4-char OSType values must Ix^ unique, and my.st not clash 
wiih tlie imcrnal DE fields types (refer lo the file 
ModuleCillback.h for a listing of OK's 4-char OSType definitions 
for its internal fields). 

WRRegisterMe rgeField t gMoJuly1D, 'BQZ1')I 
WfRRfigisterMergeField(g^odtilt‘lD. ^ii0Z2' ) : 
WRR#»Elf;terMergeField(gModuielD* ‘BQZS') t 
WliIieglsterMp.rgeField(gKoduleID, 'BQZ4D I 

When the user Ls editing a mailform, it can lx* in one of two 
different stales: metged or unmerged. Ordinarily tlie user edits a 
dcx'ument in the unmerged state. However wlien the u.sct 
presses the 'Preview' button, or before the mailform is about to 
lx printed or delivered by email, the dcx:umenL is presented in 
merged state. When a dtxumenFs state changes to the meiged 
state, our module will be notified that it must supply the data for 
substitution. Document Express will pass our moduie the 
jiiessage IIMM_GEl’Ji'EXT, and the addres,s of a buffer which 
we will use to copy our tlala. 
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figure 2 A mailform in tmmef^ed sUik^. 

Conversely, wlien the dtx:umeni is in unmer^ged state, 
rkxaiment Bxptess will send our module die HMM_GET_TmE 
mcssaj^e, and a^in, we must copy data into a buffer llowev^er in 
the unmei^ed state, we will a>py tlie field's label, as we would like 
it K> appejtr in the document and die popup list of meige fiekLs. We 
title (Hir fields <Rozo Name>, <Bozo Birthday>, <Bozd Plaa">, and 
<lJozo TiniO. (Note: it is not netess^iry to add the angle bnickels, 
as DE will do this), 

Delightful Databases 

As a cliange of pace, we will now disaiss the Dcxajment 
lixpn*,ss datalrase engine, and what we can dtJ with ii in lemis of the 
SDK. D(KT.innent Express has a well implemented API for exlrading 
contad infomiaLion. For exiimple, a module can otoin any field's 
value fiom any cx>nlael record. By extratting field diua, a module c';in 
iterate the entire database, looking for itxotds which match a tertiiin 
criteria, such as Category *= Sales, or State = CA. 

For Ikj/jo’s birdiday, we will be iterating tlie corrently ofX*n 
database, seaaiiing for Markcxl records. Marked recxirds are thase 
entries which appear in list view with a small check mark next to 
lliem. One may mark axoals for various reasf>as: marking rea>rds 
provides a quick way io make a letoid fwt of a group. 

'lb count the numlxr c?f maiked records in the currently open 
database file, we use the DE callback DBNuniberOiMarkedEnirics, 

long n - flHNuJubetUfMarkedEntrieECgModulelll) ; 

U use ti to itLTiJtc :in entifr DE dit:itKLSt!, l(K>kiiig ft>r marked ctxitact nxmls 

// id b Um: maikal rceord's sequence number a unique 324)11 viittie wtiidi itknUtk-s 

iJie // nximJ. 

forC long i Oj i < ti; i-H- ) 

id “ DHEiiirylndexToEntrylDtgHodulelD, 
HBHarkcdToEntrylndexigModulelD, i)): 

Now' that we have a inearLs t>f iterating thunigh the database 
and idcTitifying marked records, we mast extracl die cTnail address 
for each one we encxnmter Once we are in the passession of the 
marked contact's anail address, we can use the DE c’alllxick 
WRSendAfkxiiment. WRSendAlkxunx^nl Is responsible for sending 
a document via email. WllSendAl>oaiment automatically detects die 
presence of merge fields in a doaiment, and m\\ take the 
aptiropriatc steps to call liack inUj camt mcxiule, allowing us to 
peifonii our data substitution. 


Here i.s a soune Ilia for the base processing of Bozo's Birthday, 

ehort Ten: 

iDtig rsn, n = DBHuajberDfMarkedEntrleaC^odtilGlD); 
Str25S inailTo: 

Str255 raailFrom “ *'\pLinda SunRhine < Hnda@f eel good, com>'*: 
Str2S5 subjeet “ “\pLet*R Celebrate!**: 

Str255 docuiDent = '‘\pBirthday Celebration": 

for( long 1 0: i < nr 1++ ) 

I 

// obuin the marked record's sequoicr nmntxn- 

ran = DBEntrylndexToEntrylDC^oduleTD. 

DBMarkedToEnt ty 1 ndex (gHodulelD * ±}): 

// obtain the contact s email address. 

leri = slKsof (Str255j - 1: 

DGetFleldIlata(gModtileID, rsn, H D EKAILl, {char*} 

&len): 

msilTo[0l = len: 

// send the docinrveni using the DE caUbaek. 

err = WRSeridADocument(gHoduielD, connect* 

// DE doaiment to setKJ 
document * 

// matkoaddre^ 
mailTo, 

// nkaatre)m yjKt rephHo additTis 
mailFtom* 

mailFrom. 

// the message siib^xi 
Bubjeet* 

// earixm-lti CUtX*! address flf (X^eessaiy) 

“\p". 

// word-wrap text bdtjte ttdivery 
TRUE, 

a (he record sequence (used intemaily by I>E) 
rsn): 

] 


Parsing 

I3ack when we logged onto Ihe TOP3 mailbox, and correctly 
identified and downloaded a Bozo anail record, wc should liave 
parsed that message. Having extracted our Bozo data we would 
then place tl^t daUt inlcj glolrals which we amid use when our 
module gels sent die 1 IMM_GEr_TEXT meigc mcs,sage. 

Knowing bow EormMail formats our dam, we can easily 
htiild a parser to extract the field data from the rest of the 
message. Tlie FonnMail l^ERL script file which acaimpanies DH 
places discreet delimiters at the end of every field's value, which 
explains the funny +„+ sequence found at the end of each line 
tjf dam. Building a parser to extract the data values from the 
accompanying field tag is trivial. 

Branching Out 

Finally! With all our kkus and technology in place, we can now 
build a fully-featured module which supjxirts tlie notion of Bozo’s 
Birthday. We can also get more sophLstioted: we can support other, 
more complex bixxidaisL .scenarios. For example ^ why couldn’t pur 
Webform webpage support odiei paiaiixleimtl office silualtoiis, 
like the ones discussed e,;irlier in thLs article. Surely, we are just a few 
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more panimeters away from ItoKO Submit Your Timesheet, Bozo Set 
Your ClcKk, anti Bozo Be At Tlii-s Meeiinjt. 

Not Just an SDK 

'Ihe Document h^xpress Mfxiule Dtfveloper’s Kit Ls n)i)u.si in iLs 
implemeniiiLion. Ttx)Ls such as llie Softw^ire Devdopets Kit ;md the 
Module Class lihnuy (MCL) offer dev^elopers a familiar aichiteoiire 
for creating tlieir mcxlules. Document Express entxairages develofxrrs 
to use the SDK by providing a I'ully liccRsalJc and reusable 
applitaiion, combined will) avenues for marketing, pixxncxion and 
distribution, DC will provide links to tlevelope/s websites that t:Rrate 
DE modules, and offer incentives and Ixindling c>p[)ortunilies where 
appropriate. Already, sudi coiTipanies as STF Teclaiologjes liave 
realized tlie potential of DCs nuxlularity, as evidenced by tile Fax 
mcxlulc suite which accompanies Dixaimcnt Express, 



Figure i ihe FAXsf mtiduie suite. 

A Word ofUiauks 

At this point I wcaild like to extend a thank you to Mark 
'leixeira, creator t>f rXKiimeni Express, First of all, lie asked me to 
write iJiis article, hut he also proved to be an endless source of 
information, support, and kindnes.s, 1 aimplement him on 
generating a fine produa for the Macintosh and tiaving die 
thcHightflilness to create sucli a well engineered SDK. Readers who 
are interested in Document Express should take a look at 
<http://www.(locumentexpress.com>, or email <info@documentexprfiss.com> 
for further information. Also, l>e sure to hop over to 
<http://www.atpm.com> in Atiril (or sooner!!!) for my in depth review 
of Dexurnent Express 2.0. 

Why Document Expre?is? 

Tile process of generating an automated, personalized, and 
intelligent response to a web form is indeed a txjmpany's dream 
solution for automattxl marketing, supptMt and customer service 
applicatirms. Witli tills teclinology, comes a new breed of solutioas 
nev^er before thought possible. 'Ihanks to Document Express, there 
now exists a tcxil, an exteasible uxil, which can acctanplish tliese 
custt>mizcd messaging ta.sks with unprecedented ease and 
simplicity. DCs large features set, internal email and cbtab^ise 
engines, and well designed and dtx'umented SDK pnwides Ixxli 
end users and developers widi a [Krwcrful, flexible, and intuitive tool 
widi which to mamge their many methods of communication. 
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Fast Mac ISAM Access 



datato®®® 

perfornnance 




ISAI^^ 


rtiance 


Real-world data managemetii 
solutions are typically more complex 
when one examines the pieces, 

Uian initially recognized by the 
majority of database programmers. 
All software projects are complex 
puzzles comprised of many dcuiils. 
most of which are daU-related. Often 
today's “DBMS” solutions sacrifice 
the speed tir control essential for a 
competitive application. 

c-tree Plus*', by FaiiCom. has 
been the choice of commercial 
developers twenty years precisely 
because it offers the flexibility arnl 
control ai the detail level to fil a 


wide variety of data niajiagemetit 
needs. Proven on large Unix servers 
and workstations, c-tree Plus's 
small footprint and cxcepticmal 
performance have also made it the 
engine of choice for professional 
developers on Mac and Windows, 
c-tree Plus offers sophisticated 
ISAM level control with which ifie 
developer may define precise data 
management Milutions, making it a 
perfect fit for any development 
project requiring specific data 
harHlling features. 


C-t;re6 Plus*^ offers tihe mose 
mat:ure ISAM solution t:aday... 


FairCom’s 
C'-bree Plus 
database engine: 

' Advanced Indexing 'I’echnology 

• ('ompicte Source Code 

• Complete Transaction Prxjcessing 

• ODBC Interface from 
Windows clienLs 

• Over 25 Developer's 
Servers included 

• Royalty Free 

• Standalone, Multi-user or 
Client/Server Models 

- Y2K Compliant 
■ Supports Metrowerkii, 

Symantec Compilers 



The FairGom 
Server: 

A wild, high performance 
diitiibasc server that is scalable, 
portable and offers unequalled 
control, FairC:om has been providing 
database solutions to the commercial 
development community for twenty 
years and supporting Mac for nearly 
as long. You won’t find a better Mac 
DBMS solution, with these features 
and performance anywhere else! 

• Client Side Source Code 

• File Encryption 

• File Mirroring Logic 

• Full Conditional index Support 

• Full Heterogeneous Networking 

• Multiple Communication PtokjcoIs: 
ADSP; SPX; TCP/IP 

• Online Data Backup 

• Small Memory Footprint 

• Flexible OEM Licensing Option.^ 

• Sijurce Code Availability 


All tshese platiforms 
supported in one package: 

Mac. MIPS ABI. DEC Alpha. Sun SPARC, Windows 9X. 
SCO. 880PEN. AIX, RS/6000. HP9000. Sun OS. 

Interactive Unix, Linux (Alpha,,,), AT&T Sy.stcm V, 
ONX, Free BSD, OS/2, Windows NT, Windows 3.1, 
DOS, Netware NLM, & Banyan VINES. 




iEUMP 
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MEWSBITS 


by Jessica Coiainey^ <press_rel€ases@maclechxom> 


Ntw USB Floppy Enabler Available Free from 
PACE Web Site 

PACK Anri‘Piracy Inc., a leader in the development of anti- 
piracy systems for the Macintosli, released an innovative solution 
for software developers whose customers use A[^[)le Computer's 
new iMac and G3 floppy-less computer systems. PACE's USB 
Floppy Enabler is a driver that ermilates the floppy drive 
imerface, making supported tliird-parly external USB floppy 
drives work with floppy-ba.sed software products. 

PACE developed the t)SR Floppy Enabler in response to the 
needs of customers using iLs lnterU>k anti-piracy prcxiucts, a fifth 
generation tool set for proteaing, dLstributing and selling software. 
The USB Floppy Enabler currently supports Imation's SuperDisk 
and Newer Technokjgy's uDrive, two of the leading external LiSB 
floppy ,s)'stems. PACE is w'orking w'itli several mlier major USB 
ftof^py tlrive manufacturers to ensure universal compatibility. 
<htlp://www.paceap.cQm> 

FileMaker Pro Devtloper Edition Chosen Best 
Appucation Development PrcxiR^m by Software 8l 
Information Industry Association 
I'ileMaker Pro 4.0 Developer EdilU3n, the essential database 
development tcK?l kit for corporate and commercial devekjpers, 
was vtjicd Itet Application Development Program !>y the 
Software & Enfomiatinn Industry As-^^Jdation (SIJA) during the 
assfx’iation's 14th annual Codie Awards here last night. 

In winning the presrigious Codie Award for Best 
Application Development Prttgram, FileMaker Fro 4.0 
Developer Edition bested IBM's Visual Age for Java V2.0, 
Rolx>HFJ.P Office 7.0 from Blue Sky Software, St>hware 
Engineering Risk Management: Uncling Your Path dlirough the 
Jungle from LearnerFirst (in partnership with IEEE Computer 
Society), and Aion 8.0 from PLATINUM Tcchnolagy. 

FileMaker Pro 4.0 Developer Edition, estimated retail price 
$499 (in the U.SJ, gives develofXTs a w'ide array of 32-hit based 
applications and tcx)ls for compiling, delmgging, developing, 
depk>ying and managing FileMaker Pm database solutions, It 
also provides an API (A[tplication Program Interface) that alkws 
developers to write Externa! Funclionji for FileMaker Frt> 
data[)ases, a capability that w'Ul greatly expand tile ctxe 
functionality found in the suincl-alone version of FileMaker Pro 
4.0. And, with the addition of Java clasvses, FileMaker Pro 
Developer Edition also enables access to FileMaker Pro 
databases over Java<-ompliant operating systems, such as Unix 
and Solaris SystetiLs. 

<http://wvvw.filemaker.com/>_ 


ewevs 2,0 

Fiectric Fish, Inc. announces the release of C'WCVS 2.0, a 
.shareware version c:onlrol plugin for Metrowerks Code Warrior, 
which allows you to use the public domain CVS client MacCVS 
for version control without leaving the CodeWarrior IDE, 

CVS is a widely used POSIX-haserl version control system 
and CVS clients art* available tin many platforms, inducling the 
Macintosh, making it a reasonable choice for mukiple platform 
developmenL CWCVS allows Macintosh developers to use CVS 
with CodeWarrior without arcane command tine arguments or 
scripts. 

Version 2.0 features include: 

• Conversion to the kitest CodeWarrit^r Al^I. 

• Advanced dialogs for most commands. 

• Recursive command versions tor Difference. History and Status. 

• rcag .support in tlie Laiiel command. 

• Default to -kb for adding non-text files. 

• Automatic login upon connect. 

• Automatic directory creation on Add. 

• Watchers support. 

• New’ default optit>ns preferences ]>anc]. 

• Various bug fixes. 

CWCVS also comes with CWProjector, a Projector version 
ctmtrol plugin. 

<http://www.electridish.com/produas/CWCVS/> 

Paragon Scjitware RFi.FA.SFii OAK CORBA ORB for 
Apple OS X Server Piaitorm 

Paragon Software Inc., a leailing provider of CORBA 
technology for Apple products, has redeased a version of its OAK 
CORBA ORB package for Apple's new' OS X Server platfonn 
announced uxlay at die Scybold show In Boston. 

The OAK COKBA ORB is a congjlete, enterprise-dass 
CORBA development suite for building and de[iloying COKBA- 
coinpatible solutions, fi feature.s many exclusive capabilities chat 
make it a compelling choice for OS X Server developers. 

'Ihe OAK CORBA ORB is a pR>ven CORBA solution witli 
ihoii.sand.s of users in enterprise environments worldwide, 
induding demanding tclecomirvimications, financial .services, and 
Internet applications. The OAK CORBA ORB can Ik u,sed either in 
muIri-OltB environment, or as the primary CORBA solution. Proven 
interoperal)ility with all major CORBA ORBs, CORBA services, and 
CORBA third-jxirty products ensures that the OAK CORBA ORB 
meets cor porate requirements out of die Ix^x^Complete pnxluci 
literature and hilly functional 5(Klay evaluatfoii 
<http://www.paragon-software.com> Mi 
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Tracks 


• strategy 

• information 
design 

• visual design 

• usability 

• programming 

• backend 


June 27-July 1 
Moscone Center 
San Francisco 

Contact ua today for 
information on the 
conference offerings 
and how to register. 

www,mfweb*com 

phone 

( 800 ) 441-8826 
err^il 

web99@mfixom 



In June 1999, hundreds of web 
teams from around the world will 
pack their bags and Iravei, any way 
they can, to Web Design & 
Development — WEB99. 

in *96 we took you beyond static 
pages. In '9? we showed teams 
how to work together to build sites, 
filtering through the profusion of 
new technologies and techniques. In 
*98 we highlighted site usability and 
customer focus. 


In *99 il*3 still about all of this — | 

and much more. Collaborative team 
building. Leveraging technology and 
streamlining processes. Keeping the 
market share you've fought for 
Going beyond the buzzwords. And, 
as always, creating meaningful sites 
for customers. 

Learn from industry veterans and 
acclaimed educators in more than 
100 classes and tutoriats. Keynotes, 
panels and parties provide more ways 


to learn, commune and further your 
career Check out all the details at 
w w w. m fwe b xo m . 

If you’re dedicated to the medium, 
you’ll see exactly how WEB99 is 
dedicated to you and your entire 
team. Get there. 
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MiJIyr Fi’eeman 


I FROM THE 

FACTORY 

FLOOR 


By Kelly Jacklin and Dave Mark, ©1999 by Metrowerks, Inc., all rights reserved. 


Mac OS Runtime for Java 2.1 


Tliis month, iho Faaory Floor visits witli keily jacklin, a Senior 
Software Engineer at Apple working on Java runtime and JIT 
technology, Ihe newest version of MR] (version 2d) Ls about to 
ship, and Kelly was kind enough to take time out of liis scliedulc 
to share with as some of die technical details about Apple's virtual 
machine for Java, Kelly Jacklin <jacklin@apple.com> has been a 
sriftware engineer at Apple for over seven years working on a 
variety of operating system projects and related technolc^ies. He 
began work at Apple on AA.OC 3^0, Apple's UNIX operating system, 
and was one of the original team memixrrs of the Star Trek projea 
to port Mac OS to Intel, as well as a core mookemel and OS 
services engineer on the Copland project. He has spent the last 
couple of years working on virtual machine and language runtime 
technology, as has been involved with all cumendy shipping 
versions of RJ. In his ever decreasing spare time, he works on 
pointless engineering projtxts like writing scheme interpieters and 
ray tracers in Java, Aside from his engineering and familial joys of 
raising hb son Kai with hb wife Yun, he enjoys pbying a plethora 
of musical insirurnenLs (mostly stringed), much to the chagrin of 
those around him,*, 

Dave: What exactly is Miy? Is it simply a VM, or is 
there more to it tlian that? 

KcUy: MRJ, or Mac OS Runtime for Java, b Apple's language 
runtime environment for the Java programming language. It 
emulates a virtual maciiine for interpreting Java bytecode, 
supplies the nintime services Java programs expect, and provides 
versions of die core Java class libraries that map to Mac OS APIs 
such as graphics, networking, file I/O and other OS services. 

In addition to these basic senices, MRJ also provider: 
developers with the ability to c'aR the Macintosh toolfxjx and OS 
APIs, so they can write Mac applications in Java, the MRJ SDK 
includes basic tools for developing Java programs, as well as a 
powerful binding tool called J Bindery which gives devekipers an 
easy way to package their Java executables as double-clickablc 
Macini(>.sh applications; tills capability is also rather seemiessly 
intcgnited into the most recent version of CodeWarrior Pro* 

Davc; What's ficw in MRJ 2.1? 


KeUy: MRJ 2.1 reflects a single-minded goal of radically 
increasing the performance and stability of the Java platform on 
the Mac. Previous versions of MRJ, as well as third-party VMs for 
the Mac, have been either slow or buggy, or sometimes botli. 
With 2.1, we strove to correct this trend, and have succeeded in 
producing a VM dial perfonns very well, and is very stable. All 
of the features added in 2.1 reflect this single-minded approach. 
Sfx.*ciric areas of improvement include: 

• JDK 1.1.6: MRI 2.1 impiemenLs ilie 1.1.6 version of the Java 
environment and APIs, Since we use the shared JDK classes 
supplied by Sun, we have picked up many bug fixes from 
them which help provide stable and predictable behaviour 
of the Java APIs* 

• AWT: Tlie MRJ Implementation of Java’s abstract windowing 
Toolkit, has l>een completely rewritten, mostly in Java. AWT 
performance has Ijeen radically enhimced, and tills refleas 
direcily in better user-perceived, as well as actual, performance 
of most applicaiions. This new AWf implementation makes 
extensive use of the A[Jpearance Manager, willi the result that 
Java applications look very Mac-like when running under MRJ. 
Tills has also been an area in which we have gready improved 
our stability and correciness, where correctness is refletted both 
in adheience to the Java specifications for die APIs, as well as in 
developer expectatioas where the specifications are ill-defined. 

• Cross-platform Consbtency: Many Java developers have Iteen 
ignoring the Mac, simply because the Java imj)lemeniations on 
the Mac have lacketJ the maturity or predictability of behaviour 
that they have ccome to expect from Jav'a implementations on 
Windows. We have geady enhanced the consistency of our 
platform, which allows developers to bring their Java applications 
over to the Mac easily and successfully with very little pain. 
Where spedficaiions of API behaviour iiavc Ix-cn ill-ddined, we 
have assessed die behaviour of the AI^I on other platfonns, and 
gone with the de-facto .standartl expeaed by developers. 

• Networking/Security: Ihrou gh the u se of asynchronous 
networking using OpenTmnspon, MRJ 2.1 exhibits gready 
enhanced networking perftirmance, maintaining 
asynchronous execution of oilier Java direads wlule threads 
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perfcirming network apcmtions remain highly responsive to 
cainpletion of outstanding requests. MRJ 2,1 also reflects 
improved support for networking and security services, such 
as ItMIC, JDBC, encryplion/decryption and code signing. It is 
important to note that while there were bugs in some 
security features in MRJ 2.0, those bugs manifested in lack of 
functionality, rather than security holes. 

• SDK: We have improved our support for Java development, 
by providing better basic Java development tools, as well as 
working witfi ibird parties to improve tlie support for MRJ in 
ilicir tcx:>ls. CodeWarrior now has built-in support for 
generating executables diat use MRJ, and their debugger 
works very well with MUJ. Tn addition, MRJ 2.1 allows Mac 
developers to write Java applications that call the Macintosh 
toolbox and OS APIs, tlirough the use of wrapper cks.ses 
automatically generated from the universal Mac OS headers. 

• Ti treading and Synchronization: 'llie lowdevel VM support in 
MRJ for threads and synchronization .services has Ix.'cn 
completely rewritten tn 2.1. Tills lewTite represents much better 
perfonnance in areas of cotexi-switching and scheduling, and 
provides enhanced scheduling support in areas like prit>rity 
inlieritance for monitors and condition variables. Tliis lias hid a 
direti impat.! on Ixjtli lK‘ndiimrk scores and real-world server 
applications or coniputationaliy intensive code. 

• No 68k Support: Radical improvemenLs to a product often 
come at a price. In tlie case of MRJ 2.1, this price was paid in 
lack of support for 68k machines. The complexity of the project 
demanded tliat we sacrifice support for thi.s piix:cssor, sup|X>rt 
for which retjuired Uxi mudi duplicate engineering and would 
have caused us to deliver much needed improvements to our 
developers much later. Feedback from most of our 
development community has shown overwhelming support 
for, or at least sympatliy with, this decision. 

• Just-in-time Compiler: One of the more radical enlianccments 
to MRJ has come with the introduction of a new jrrc. For MRJ 
2.1, Apple has an agressively optimizing JfFC that far exceeds 
the performance of our previous JITC. We have also enhanced 
this jrre to provide belter interaction Ixilwccn Java code and 
certain natively-dispatched calls, such as the Macintosh toolbox 
APIs, Tliis has dramatically improved performance of Java code 
running on our VM in general; which improvement is even 
more pronounced for computationally-intensive code or long- 
running server applications. In addition, the deployment of this 
jrre has provided us with the flexibility to implement mudi of 
MRJ itself in Java, providing increased robustness and feature 
richness, wiiiic still providing competitive performance. 

Dave: We hear lot about Just-ln-Hjne compilers. How 

docs a JITC work? When are methods compiled by a JITC? 

Are all JlTCs strictly dynamic? 


KeUy: Basically, a Java .flTC is a dynamic recompilation 
engine for tmaslating bytecode into native instaictioris. The JITC 
is dynamically loaded during startup of the Java virtual machine, 
and plugs into the VM through a set of h<K>ks. When classes are 
loaded by the VM, the JITC Is notified, and it can decorate the 
class meta-data with information it w^Ui later need to compile the 
methods of that class. Implementations of JlTCs vary from simple 
strict translators to optimizing compilers, and run the gamut in 
lx:iween. The JITC included in MRJ versions 1.5 and 2.0 
perfomied fxasic translation of the byfeccxie stream into an 
equivalent native instmetion siroam, witli a decent register 
allcKator to improve tlic perfonnance. The advantage of this JITC 
was its extremely low cost in compilation, at the expense of 
runtime performance of die translated code that paled sornewliat 
in comparison with JlTCs in cuiiijx:tiUve virtual auicliines. Tlie 
new JITC introduced with MRJ 2.1 offers much more compelling 
perfonnance of compiled code. However, this performance 
advantage comes at the cost of increased compilation time for 
complex meditxis. We liavc mitigated this cost using some of the 
mechanisms commonly used in JIT technology. 

Compilation is typically performed on first invtxraliQn of a 
methrxl. However, with any JIT technology other than the most 
primitive, compilation can be computationally expensive for 
complex methods. For this reason, it is often better to defer 
compilation of a method until it is known that the speed 
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increa^sc of the compiled code would make up for the cost of 
compilation. This can done l>y applying heuristics to allow a 
method to be Interpreted until it is detennincd to Ix! frctfuently 
t.’alled» at which time it is compiled. A JITC can also make use of 
the Java VM's tJircading services to defer compilation to a lower^ 
priority background thread. In these ways, ilie cost of opLimi;^ing 
compilation can be amortized or deferred so that it is not 
noticable to limc-eritical or user-interface code. 

It is also ptrssihle for a JITC to cache the results of 
compilation for use by a subsequent execution* However^ due u> 
the dynamic nature of the Java language, this typically involves 
i;>loating the code, or having ctjmjrlex fixup data sunecl with ihe 
code, so that tiynamic conditions can be updated when the eexJe 
is restored. Such conditions include, for example, whether 
de[X^ndenl classes have been statically initialized or not, as well 
as things like the constants values lor field offset and nicihod 
table offsets that ran vary as classes Uj>on which the target class 
is dependeni art* changed. A JITC that riches compiled code is, 
by its nature* not siricdy dynamic* 

Dave: What kinds of optimizations can a JITC 
perform? And are there specific coding technii|ues 1 can 
use to make my code more JTTC friendly? 

KelJy: A JITC can perform any optimization that maintaias the 
correct behavitxir of the Java code, tis dcfineti fry the spcxlfirilions. 
Jliis includes iniditional optimizations* such as various loo[> 
Imasformarions* common siib-expiession elimination, global register 
allocation, dead ctxle eliminatjt)n, t:r>py pmpogation, etc* In 
addition, die Java language lends itself well to several OOKeniric 
optimizations, such as monomorphic dLspiitch optimmition and 
meUiod inlining. Since, in Java, the majority of instanre' metliotLs 
require virtual dispatch, OfXimizing virtual dispatch to melhtxLs tliat 
cm be proven fo have only one currt^nt imjilementation ran a 
big win. Most JlTCs do diis untxindttionaUy for dlsjxitches to any 
methods marked widi die "‘final'’ keyword* or any mefhexis 
belonging to classes marked wiili that keyword, so appiopriaie use 
of this keyword can improve performance. One must careful, 
however, not to unnecessarily lestrici ctKie with aggressive use of 
the "tiniir keyword, as this keywoid makes sul>-ckssing difificuli or 
impossil)le, thus s:icrifidng flexibility in the usage model of the cLiss. 

In general though, developers should not be too cognizant 
of the presense of a JITC, other than the fact that their code 
performs well 'IJie Jl fC in MRJ 2*1 performs optimizations in 
places lliut would surprise the average developer, and which 
cannot fie expiiiitiy ccxled for in advance. Developers should 
trust the JITC lo do its fob, and not try Li> second-guess ii in their 
code. In some c:ases, attempts that a develoix^r makes to 
anticipate optimization will backfire. Some tools that “optimize'* 
the Java bytecode in a class, for example, would defeat later 
oplimiz,;ilion effons by the JITC that shipped with MRJ 2*0* 

Dave: Once the^ITTC has generated PPC code, how do^ 
dial cikIc interface wiUi ihe VM? 


Kelly: Wlicn tlie JITC starts up, the VM establishes a set of 
callbacks into the VM for the JITC to use, Ixidi during compilation 
and during mntime. Information is stored by the JITC in the meta¬ 
data ft)r a meihcxi which allows the VM to invoke the generated 
native code for that metllod. Similarily, lliere is information in the 
metaniata for methods that have not lieen compiled on how to 
invoke lliat mcthcxl using the VM. The transitions are handled 
through data-driven dispatching iKXllcnecks. These Ixjttlenecks 
facilitare bidirectional "mode switches" Ix^twecn Java and 
compiled native cxKie, .similar in concept to the co-existence of 
PPC and 68k emulated cxxle under MacOS. 

In addition, both the JITC and VM provide a number of 
"helper" functions that can be called by compiled code* This 
includes c^xJc to tx*rform such operations as object allocation, 
math routines, Java exception processing, and inmsiiions out of 
Java into statically compiled C/C++ code. 'ITtese routines are 
made available lo the compiled code through linkages 
established at compile lime. 

Dave: What facilities exist to allow progniramers to 
mix C/C++ and Java within a single program? 

Kefly: java supfx:nts c-alling C/C++ axle from Java* as well as 
invoking Java fn)m cyc++. The fata lilies in CyC++ that allow this are 
coUectiveiy termed tiie Java Native Interface (JNl) APIs. Calling 
C/C++ code from Java traditionally axsiimes lltat the C/C++ axle is 
aware that it is being called from Java, which has lequiied 
develofKTS to write bridging ctxle t<j map java interfaces onto their 
existing or legacy code. Tliis has lx.x-n a [)roblan for many 
rlevelopers. To help ease diLs integration problem, as well as ease 
our own internal tlevelopmenr of MRJ itself, MRJ also supports a 
proprietary native axle inv^xution mcxlel allied JDitea, as well as 
the traditional Java-supported meclianlsias. JDiieci {ntx to be 
confu*se(J with J/Diroa, which is a Mienrsoft lechnolc^) allows 
Java code to invoke native shared-liljrary-lxised rt:)Utines directly, 
without the need for wrapper axle written in C/C++. It takes care 
of kxrking up the nxitine by .symbol from tile appropriate shared 
library, and maishailing p:irameTers from Java into the native calling 
ctxivenlions and calling tile target n>uiine. TliLs technology forms 
the basis for acxess to the Mac OS APIs provided by MKI 2*1. 

A closely related topic to the invexation integration lietween 
native and Java axle is the ixsue of emliedding Java content within 
the wintiows of a Mac application, MRJ 2*1 provides an emlx^dding 
Aid, called JManager2, wliich allows applications to host Java 
content ift*sidc of tlieir appliesition windows, or in separate windows 
devoted to Java content, li pitwidc's API*s to manage wimlow real 
estate, as well as to delegate events and give time to Java ccxlc 
running within the applic'ation, For example, JManager is used to 
emlx*d Java cxJutcnL inside web brxiwser windows in MkTOSoft 
Internet Explorer. Using these APIs and services* developers am 
integrate native code with Java code all in the .same application. 
Tills gives developers the flexibiliry to write portions of their 
applic'atioiiio Java, or to use Java as a plug-in lechnoksgy to allow 
their application fiinaionaliiy to be extended by third i>aitics in a 
cRxss-platform and compatible fashion. 

na 
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hy Jeff elites <online@maciecb . com> 


Make your applications scnplable. 

The advice is as simple as iliai. 

The standard reasoning is that by ni:iking your applicatk)n 
AppleFvent-aware, you make it mewe valualile — users can automate 
rujx'titive tasks and incoqioratc your product into a lati^cr woikflcjw. 
Recently 1 was reading the FAQ for tlie popular FTP client Anarcliie Pio 
(by Stairw^ays Software)* the question on the table was, "Why don't you 
give Anairhie the ability U) rcpeattxJly tx>ll busy FTI^ sites until it can get 
Tlie answer was tliat diey dont W'ant to add this feaaire, because it 
would be a dLssenace to the already-busy FT? sites, but you can achieve 
file same efftxl using AppleScript. I found this intriguing nor only 
docs soiptabiliiy save tlie atiihors rmni having to program in iliLs 
ftinctionality tliemselves, Ixit also it allows them to discoumge using their 
protlua this way, but still allows the user to make the final ciec'ision on 
llie rnaUcT. Tliat is tlic gem t)f scriptability — eniptjw'cring your users to 
use your pioduct in ways tliat you diclnT predict. 

lliere's a second, more siibfle motivation to making your 
applicaiLions AE-aw'are — it makes your design better If you want tc) 
make your a[)plic'alion exlcasivcly .sciiptablc (and recordable), you 
need to factor it coneaiy — to separate the U1 from the 
implementation as much as possible. One method for doing this is tiie 
Model-View-Controller (xtradigin, which incidentally is the way most 
Yellow box applications ai*e developed. So thei^’s a nice haniiony here 
— factoring your applications to make them salprable also prepares 
you for later moving to Yellow Box development, anil Yellow Box 
development Ls by default done in a maimer wliich makes it trivial to 
add extensive scripting capabilities to applications. 

iTiere are three sepiirate iLspects of AppleKvenLs w'hich might he 
iin[X)rlant to you as a progmmmLT: making your application AppleEvcnt- 
aware (your a]:tplicatian is an AE^server), controlling otlier applicatioas 
with AppIeKvents (your application i.s an AE-client), and writing 
applications in AppleScript iLself. This month we aie g<)ing to point out 
some informational resources for cacli, ;uid next inontli well kxjk at 
.some utilities and lil'^nmai to help with the implementation. 

Gettino Siartei) — General Resourcius for Developers 
T'lte definitive references of course come fioni Apple. Tlie 
Interapplotion Q^mmunic’ation (lAC) section of their Mac OS 8 
Dt:vdopt:r D(K:ufneniatitHi provides pointers to ilie essential pubrotions 
and tecdinotes, including tlieir ApplcScrifit for Devcio[X.-rs |Xtgc. AnotJier 
key resource is articles horn back-issues of Apple's now-defunct journal 
deifeUp. They have a page which collects links to all of the I AC anides, 
and tlicsc aie also all available in HTML fbmi, complete w^iili 
accompanying sourex^ ctxle, on MacTecb '$v^&^ site. A similai; annotiited 
list Ls available on Main Event’s site. For a printed reference, 1 highly 
recommend Dave Mark's lIlturuMc* Mac Pn^mmmin^ (ISBN l-568ikT 
1S^7)* IXm’t let its uninfonnative title l’a>l you — alxrut a tliiid of this 
thick volume is devoted to getting the developer up to speed with all 


things AppleEvent-relattxl, and [ have yet to find a reference whidi d(x;s 
a IxaicT jol) of explaining Uic subject and gearing you oriented* 

Mac OS 8 Developer Documentation: Interapplication Communication 

<http://developer.apple.com/tedipubs/macos8/lnterproCom/ 

interprocom.htm[> 

Mac OS 8 Developer Documentation: AppleScript for Developers 

<http://developerapplexom/techpubs/macDs8/lnterproCom/ 

AppleScriptDev/applescriptdev.html> 

develop Articles on Interapplication Communication 

<http://developer.applexom/dev/techsupport/develop/bysubject/iac.hftnl> 

develop in MacTech 

<htlp://www.nnactech.com/artfcles/develop/> 

Main Event - Resources - Articles 
<http://www.mainevent.com/arTicles.trTipl> 

For a glimpse of the future, fake a kx>k at the Scripting 
documentation for Mac QS X Server. Yellow Box applications will get 
a great deal of .scTipiabilily ‘Tor free”, and it will l)c easy to extend 
their scriptability fmther. Scripting fits nicely with the Yellow Box 
application model, and promises to have a bright future under Mac 
OS X later this year. 

Mac 05 X Server Developer Documentation 
<http://developerapplexonfi/techpubs/macosxserver/macosxserve(;html> 


M*4KLVG Your Appi.ication AppleEveistt-Sawy — 

IVo Key Ar'i jcles 

Included among the develop articles mentioned al>uve are two 
that i think are key, Ideally you would read all of them, but failing 
that check out “Programming for Flexibility: The Open Scripting 
Architecture” which is foundational and really gives you a feel for the 
power of Apple’s scripting architecture, and “According to Script: 
Attaching and Embedding Scripts’" which I hope will sell you on the 
virtues of this (Towerful but underutili>'ed lecimique (The simplest 
example is just providing your users with a “scripts” menu.) 

June 94 - Programming for Flexibility: The Open Scripting Architecture 
<http://www.mactech.com/artjdes/develop/issue_18/026-040_SMiTH_REV.html> 
June 96 - According to Script: Attaching and Embedding Scripts 
<http://vvww.rnactech.com/articles/develop/tssue_26/according.html> 

Stay tuned for next month, when we’lt covei’ development tools 
to make your AppleEvenl program mi ng a breeze. 

These and a bevy' of other links are available from the MacTecfi 
Online web txiges at <http;//www.m3aechxom/online/>, 
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TIPS & 
TIDBITS 


by Jeff elites <online@mact€cb .com> 


Shortening Verbose 'aete' Rf^sotircrs 

AppIeScriptsibility i.s a vt^ry useful feature to iinplenicni in your 
applications. Tlie Ix^st way to edit ‘aete’ (scripting terminology) 
resources Ls to keep them in text term and compile them intr> your 
application with Rez. One prcjblem with this is llic large numtx:^rs of 
“reserved” lines that make it hard to see much of the real information 
at once. However, you can compad these lines down with the help 
of macros like the following: 

/*''rTcscrvcd 10" expands to 10 lines of“Tt^ervcd”V 

#deflne reserved10 \ 
reserved. \ 
reserved, \ 
reserved. \ 
reserved, \ 
reserved. \ 
reserved. \ 
reserved. \ 
reserved* \ 
reserved * V 
reserved 

and similarly defining “mservedir Uj expand to 11 Itnes of 
"reserved”, and so on for “reservedlZ" and “reserved 13”. 

Once youVe done this, you can use these maaos to make your 
terminology entries much more compaa. For example, here’s a 
aHTiplete denniiion for itie “quit" event in one of my at^plicaiions: 

’'quit', 

"quits the application”* 
kCoreEventCiass. 
kAEQtiitApplication. 
noReply, 

replyOpttonal, 
single!ten. 
notEnumerated. 
reserved!!, 
noParams. 


kAESpecialClassProperties* \ 



reserved, \ 
singleitem, \ 
notEnumerated, \ 
readonly, \ 
reservedll, \ 
plural, \ 

1. /* Properties 7 \ 

( /• Elements V ^ 

1 

and here's a partial example of its use in a class definition from 
anotlier of my scriptable applications: 

".serial port". 

SerialPortClassTD, 

"an RS232/RS4:?2 serial port.”, 
f t Properties V 
"natae", 
pNajne, 
typeChar, 

"the name of the port", 
reserved, 
single!tern, 

notEnumerated, 
readonly, 
reservedll, 
singular, 

\ , t Properties 7 
i rBcmems7 

"serial ports". 

SerialPortClassTD, 

"every serial port". 

PluralForm, 

Lawrence D’Oliveitv 
<ido@geek-central.gen.nz> 


directFaramOptional. 
singleTteifi, 
notEnumerated. 
changesState. 
reservedl2, 

I /’■ OlherRdrams 7 
"saving". 
keyAESaveOptlons. 
enumSaveOptlons, 

"what to do about saving changes”, 
optional. 

enumerated, 
reservedlQ, 
notEeminine. 
notHascuHne, 
singular. 

[, Otht-rPamms 7 


Here's another macro for shortening verbose ‘aete’ resources, 


Disappearing Apple Menu Submenus 

I was asked about this several times during MacWorld SF tills year 
so 1 thought it warranted a tip. The cjiiestion was, ^"Wfiy am lliere no 
submenus under tlie AppleMenu in my prognua^ My Mac programming 
texts don't mention anything, but tliey show tlie submenus present in 
their screen shots.” Well, here's the semp: Apple Menu Options, which 
creates these submenits, automalioilly disables lliis feature if it detects 
iliat memory is low when it initializes. If you call MaxApplZone() at the 
lieginning of your program, right after you initialize die managers* then 
you will get your submenus — this call expands the appliraiitm heap 
zone to the application heap limit, so tJiat Apple Menu Options no 
longer mistakenly thinks tlmt it is out of memory. Incidentally, this is the 
same cmimstance which can cause Navigation Services to silently fail 
(This call wnll also help to minimize heap fnigmentation, and you sliould 


this time for convenient definitions of plural forms of class names:_ 

tfileriiiE FluralForm \ 

i /• Properties 7 ^ 


use it. anyway,) So now yrai know. 


C^Df a tip? Write to tips@ma€tech,com 


'Hps and Tiourrs 
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How Biliicft do vou nay 




for network consultation? 


I ft- i 


1 


.M:- 


How does FREE sound? 


V.:'. ■’ 




^ M 


FmiMon 




Get Your FREE Personal 
Network Consultation 
with Dr. Farallon 


At absolutely no cost Dr. Farallon's network experts can help you. 


✓ Implement switching to optimize your current network 


✓ Upgrade your Macs, PCs, servers & printers to Ethernet or Fast Ethernet 


✓ Integrate lOBase-T & 100Base-T with 10/100 hubs & switches 


✓ Budget for network improvements & plan for network growth 


Call: 1 - 800 - 613-4954 

Visit: www.farallon.com/dr.farallon/mactech.htinl 






-V'". - 









.. J 




'"For free, a Dn FaraUon 
Network SpedaFsr analyzed 
our existing system, identi¬ 
fied a range of optionSf and 
helped us plan and install a 
network with the speed and 
capacity we need at a price 
we could afford." 


Irene Ogus^ CEO, 
Media Corps 
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Abddin Krxmiet^* Systems liiL ... 

.5 

Bed live ......... 

. ....59 

Developer Depot.. 

.. 28-29 

FairCxMii ...... 

.63 

Rimlktn . 

. 71 

Gars^ecom ..._____ 

.. 21 

MacHack . 

..9 

MacTuiirDROM 

. 15 

1 

1 

F 

. .1 

Metrowerits ... . . 

. RC 

Onyx Technology, Inc. . 

. 55 

Fiuida\litvc- . 

.. 25 

Quadrivio Corporation . . . 

. ...55 

Rainbow^ i echnologies .. 

. ihx: 

REALSoRware ..... 

.. .......15 

.Sdentilic Placement . 

. 45 

SttmcTablct Rublishing _ _ _ 

-43 

ISB Stuff .. 

.. 67 

Web 99. 

....,.,,.,....65 

Water's Edge Soflwaie .. 

..19 

//Kalo ...... 

.IBC 



ADBEJevice • Ik^eHive...............*.59 

BuglJnk • l^ambWave.......................23 

CD ROM • Mac'lech CD ROM..................15 

c-tree Plus • FiiirCom.............65 

Classified • Sdcntific Placement, Inc,..,......,.,..68 

CodeWarrior” • Meirowcrks..................BC 

Developer Tools • Developer I>ep<)t.......28-29 

Equipment • USB Stuff....*..........33 

Event • MiicHack.........................9 

Event • Web 99.......................65 

Garage.com * Gamge.com................21 

General Edit * Quaclrivio Corp........................53 

Internet Connectivity • Zocalo.............IBC 

MacHASP • Aladdin Knowledge Systems Ltd..........5 

Network Performance Products • Farallon........71 

REALbaslc • RliAL Software..................69 

Resorccrer' 2 • Mailiemae.stlictics, Inc............ 

Sentinel * Kamliow Technologies.........IFC 

Spotlight " * Onyx Technology, Inc,,...........,...47 

SioneTable • StoneTablet Publishing.,,..............41 

Tt>oLs Plus"* • Water's Edge Software,.............51 


VIk' in<k'X nn Ihts pag<L' Ls pnjvkktl ks a st'tvkx^ lo our nt^ifk:rs. Tlir piiSlislu^r tkH?,s noc iL^sunit' any iLiljiliiy for trrurs irr ortjtsuiini.'i. 
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No Cute 
See-Through 
Green Panels 


Unlike some high-tech companies, Zocafo 
isn't reaching out to the mass market. 
We've been serving business, industry, 
and higher educofion exclusively For 
more than a decode. So your business' 
Internet traffic doesn't queue up behind 
some kid's game of Doom, and youc 
network staff don't hove to wait on hold 
' to speak to our technicians^ 

By focusing on the higMspeed networking 
needs of businesses,- we've been able to 
build an Internet Dackbone that provides 
belter than 99.995% overall uptime. 

With peering at mpre West Coast 
locations than any other ISP,,^e're 
uniquely able to route your company's 
critical dota around Internet slow-downs 
and trouble-spots. Our managed 
multiprotocol network is the only one of 
its kind, allowing Zocalo albne among 


ISPs to offer n'otive routing of AppleTalk, 
IPX ond DEC net between customers' 
office IKNs throughout the world, at 
speeds up to 45 megabits per second. 
We also deliver fully-configured 
equipment, proactive customer service, 
on-site mointenance, and a firewall 
custom-built to your specs, all at no exfra 
charge. We take responsibility for your 
wide-area network and Internet 
connection right up to the FDDI or 
Ethernet jack in each of your offices. 

If cute just isn't enough for your business, 
call our network engineers and find oyt 
why Zocalo is the first choice for 
industrial-strength business networking. 

-1-1 510 540 8000 
ihfo@zoeab,net > 
ht1p;/i/www, zocalo. net 






Whoa. New technology. 
I need updated tools. 




CodeWarrior solves problems. Rely on us to stay current witfi Apple's 
latest technology and to be standing by with the software development tools 
you need. CodeWarrior offers full support for Mac OS Appearance Manager, 

Mac OS Navigation Services, Mac OS X Server G/C■t''^^/ObjC and Mac OS to Mach-0 

cross^comp ller. CodeWarrior - still fast, powerful^ easy to use. __ 

No p robI efn with the t ^ ri g h t ? 

PROBLEM SOLVED. CODEWARRIOR. 

1.800.377.S416 

For more information on CodeWarr1 or's support for new Apple technology, check out: 

www.metrowerks.com/newtech 






















